Memory
CONTRACT DRAFT — MINI_SPHERE_CONTRACT v0.2 (DRAFT; Sep 5 2026; incorporates DP-MS discussion, instruction kind, getBrief() grounding, AgentSphere boundary note, SurrealDB Agent Memory comparison — pending AgentSphere conversation in a separate session). Parent: SPHERE_GATEKEEPER_CONTRACT. Reference baseline: the live sphere db/schema.sql (D1 SQLite), with documented deviations. Evidence standard a5e10e10. Spike evidence: FTS5 confirmed, recursive CTE confirmed, DO alarms falsified (scheduled-tasks gatekeeper substitutes) — see design entry 03005dfe. Section 1 PURPOSE: every workspace gets a memory/map layer as a blueprintable Gadget DO with SQLite — the substrate the workspace agent navigates by: what exists, how it works, what was decided, where authority lives. Contract-first: if a memory capability is not described here, the gadget does not provide it. Section 2 DEFINITIONS: Mini-Sphere (the gadget); workspace agent (the consumer, via Cap'n Web RPC — no MCP surface); optional binding (a wired gatekeeper/AI binding for semantic/LLM features, default off); scheduled-tasks gatekeeper (maintenance scheduler, not an approver). Section 3 SURFACE (direct RPC, no MCP, no approval queue): Reads: recall(query, {topK, tag, kind, hops, full}), listRecent({n, tag}), getEntry(id), connections(id), getTags(), getCount(), getStats(), getBrief(), graphView({seedIds, hops}). Writes (immediate, caller-classified): capture(content, {tags, source, volatility, kind, status, importance, claimTag, evidenceRef}), append(id, addition, {...}), update(id, content), setStatus(id, status), forget(id), link(src, dst, type, {provenance, weight}), unlink(src, dst, type). Maintenance (gatekeeper-triggered): runStalenessPass({limit}). Section 4 DATA MODEL: entries(id, content, source, created_at, updated_at, recall_count, importance_score, claim_tag, evidence_ref); tags(entry_id, tag) normalized + dedicated indexed columns for status/kind/volatility; edges(src, dst, type, weight, provenance, metadata, created_at, updated_at, UNIQUE(src,dst,type)) with 8 closed types (relates_to, supersedes, caused_by, decided, about_person, part_of_project, follows, document_of), kind-gated, symmetric relates_to canonicalized by id order; revisions(entry_id, content, at) for history; fts5 virtual table over entry content (BM25). Lifecycle status canonical/draft/deprecated; volatility durable/state/volatile; kind episodic/semantic/instruction; provenance explicit/inferred/system. Section 5 RETRIEVAL: BM25 keyword arm (FTS5, spike-confirmed) + graph hops (recursive CTE, spike-confirmed) fused via RRF; rerank = time-decay (volatility floors 0.9/0.6/0.15) x log1p(recall_count) x importance x tag-overlap, MMR lambda=0.7; snippet budgeting (top-2 get 4000 chars, tail 400, total 12000); temporal query rewrite returns queryUsed; filters drop deprecated + pipeline exhaust. Scores recomputed per request (no result cache — matches the live substrate). getBrief() returns standing instructions (canonical, non-deprecated, kind=instruction) alongside stats/staleness rollup — the grounding role for the workspace agent's "read FIRST when picking up" handoff pattern. Section 6 OPTIONAL BINDINGS (pluggable, default off): VECTOR/embedding binding → semantic recall (vectors as BLOB, cosine in JS over candidate set), semantic dedup (0.95/0.85), auto-linking (>=0.78), contradiction detection; LLM binding → classify fallback, digests/roll-ups, auto-patterns, query-tag inference; RERANK binding → cross-encoder reranking (optional, for production relevance gains). The gadget is fully functional with ZERO bindings. Section 7 MAINTENANCE: scheduled-tasks gatekeeper fires runStalenessPass on a cron (narrow named method, least-privilege, audited per run); lazy staleness on read as fallback. No self-alarms (spike: Facets cannot set alarms). Section 8 OUT OF SCOPE: MCP surface; approval queue; gatekeeper write-aperture; ingestUrl/crawl/document-extraction; cross-workspace traversal; live queries; SurrealDB/VPS substrate. Section 9 UNCERTAINTY-AS-NATIVE: claim_tag ([VERIFIED]/[INFERRED]/[UNKNOWN]) + evidence_ref as real columns — a5e10e10 as data, not convention (implements what the v2 vision only describes; the live sphere lacks it). Section 10 AMENDMENT: PRs against canonical in int_contracts, via gatekeeper-github, version bump + re-pin + verbatim duplication + evidence snapshot. Conflicts reported, never improvised around. Section 11 NAME: MINI_SPHERE_CONTRACT, registered per NAMING_CONTRACT; parent SPHERE_GATEKEEPER_CONTRACT. Section 12 DP-MS RULINGS (pending formal ratification — all recommendations adopted with three clarifications): DP-MS1 tags: normalized table + dedicated columns (yes). DP-MS2 history: revisions table (yes; FTS indexes current content only; append writes to revisions and refreshes current row; snippets render from current content). DP-MS3 vector arm: in-scope, default off (yes). DP-MS4 caller-provided classification: adopt (yes; omitted caller classification defaults to draft status and conservative kind/volatility; canonical requires explicit caller assertion or the LLM-classify binding). DP-MS5 dedup: hash baseline (yes; exact-hash means raw stored bytes, unnormalized). DP-MS6 digests/auto-patterns: drop (yes). DP-MS7 uncertainty-as-native: in v1 (yes). DP-MS8 staleness: scheduled-tasks + lazy fallback (yes). DP-MS9 contract placement: separate child contract (yes). DP-MS10 FTS5 keyword arm: evidence, not a decision. Section 13 AGENTSPHERE BOUNDARY NOTE (pending AgentSphere conversation — name being retired, functionality distributed): AgentSphere owns coordination state (who, what work, what plan, what messages) — mini-sphere owns knowledge (what happened, what was decided, what's true, what's uncertain). The natural handoff: when handoff_work fires, the handoff note ("read FIRST when picking up") is a mini-sphere episodic capture, while the plan state itself stays in the coordination gadget. Without this line, the coder will face an ambiguous call the first time the workspace agent wants to record "task X completed." Naming: "sphere" is a formal capability class (memory/map); AgentSphere is not in that class (coordination). The ecosystem will have both "sphere" gadgets and "agentsphere" gadgets per workspace; contracts in int_contracts will intermix the vocabulary. Worth a naming-contract pass: either the rebuilt coordination layer gets a name that doesn't read as a sphere-class capability, or MINI_SPHERE_CONTRACT explicitly disclaims coordination verbs. Section 14 SURREALDB AGENT MEMORY COMPARISON (for context — not a contract change): SurrealDB Agent Memory (formerly Spectra/Spectron) is the released product matching your v2 vision: six categories (episodic, identity, knowledge, context, instructions, uncertainty), tri-temporal clocks, supersession, provenance, T1-T4 tiered retrieval, traces as first-class nodes. Mini-sphere covers episodic/semantic/knowledge/uncertainty natively; context is correctly absent (hot state in the DO); identity and instructions are the gaps. Identity stays edge-based (about_person); instructions are now kind=instruction + getBrief() grounding. The gaps are real but mostly LLM-bound/scale-bound ones deferred to bindings. Mini-sphere remains the only memory shape that satisfies the actual constraints (in-gadget, no-egress, zero marginal cost, blueprintable per workspace), and it's contract-shaped to swap behind the same API surface. STATUS: DRAFT — pending AgentSphere conversation in a separate session, then formal ratification + pin. RELATED: 03005dfe (design), c51653de (prior contract draft), 9c51aced (work item), 3e1f9f20 (sphere substrate), 2144b79b (three-layers boundary), 0b8f273e (AgentSphere callsign coordination), 4df88ef0 (mission/vision), cf00a760 (foundational vision), 6ed41ea6 (gatekeeper-family principle), a5e10e10 (evidence standard).
Tags: docuclear, mini-sphere, contract, draft, project:docuclear, duplicate-candidate, kind:episodic — Source: mcp — 2026-09-05 03:09:57 UTC