Memory
MINI-SPHERE — FULL TRANSFER PLAN (captured Sep 4 2026 by the workspace agent, for handoff to a new workspace). Self-contained: a fresh workspace with SPHERE + CONTEXT connected can reconstruct everything from the IDs and pin below. 0. THESIS: Mini-Sphere is a blueprintable Gadget giving each workspace its own memory + map layer — nodes, typed edges, recursive recall-with-hops — backed by SQLite in the gadget Durable Object. It closes a parity gap: the workspace agent has no in-workspace memory (only external SPHERE + CONTEXT bindings), unlike the think agent which has a knowledge DO + memory store. Workspace-agent-native form of the sphere capability class: NO MCP surface, NO approval queue, NO governed write-aperture — the consumer is the workspace agent calling the gadget DO directly over Cap'n Web RPC. Parent: GlassAgent platform / DocuClear product. Child boundary of SPHERE_GATEKEEPER_CONTRACT. NOT the SurrealDB/VPS substrate (3e1f9f20) — it is the workspace-local SQLite port of the ACTUAL current sphere semantics (D1 SQLite + Vectorize + Workers AI), minus Vectorize and Workers AI, plus optionality. 1. PROVENANCE & KEY REFERENCES: - Contract pin (SHA-256): B846EDB4DB3F1F6D3E30534974D30ECCE59F1F9FC6D940E151627FB2D18D60F7 - Evidence-store snapshot: collection c2f7ca03-a02c-4f3c-bf31-2a938b8b56e2 (docuclear-evidence), path /contracts/MINI_SPHERE_CONTRACT@0.1.md - Sphere design entry: 03005dfe-509d-4cbc-833e-e00dc087020f - Sphere contract draft entry: c51653de-509b-41b6-9032-0c6832d58644 - Sphere DP-MS ruling entry: 667f1251-dc8c-476f-8852-4913d8272247 - Sphere mini-sphere work item: 9c51aced-d817-4327-bc0a-e108b5b2a155 - Sphere substrate work item: 3e1f9f20-02a9-42ac-bc4a-62e0395d5555 - Sphere three-layers boundary: 2144b79b-8b55-4b07-bfe8-62f26d40581b - Sphere foundational vision: cf00a760-9412-43bb-b63c-127421cea4aa - Sphere gatekeeper-family principle: 6ed41ea6-c0c7-48a1-9cfa-34cd42438bdc - Evidence standard: a5e10e10 (a contract, not a sphere entry) 2. SPIKE EVIDENCE (proven in a throwaway gadget DO): - FTS5 AVAILABLE: CREATE VIRTUAL TABLE ... USING fts5 + MATCH + bm25() + ORDER BY rank returns ranked BM25 results. Keyword arm = BM25, not LIKE. - Recursive CTE AVAILABLE: BFS graph traversal depth 0-3 over nodes+edges returns correct reachable set with paths + edge weights. Hops mechanic ports verbatim to one recursive CTE. - DO alarms FALSIFIED: "Facets currently cannot set alarms." Gadget DOs cannot self-schedule. RESOLUTION: scheduled-tasks gatekeeper fires the maintenance RPC on a cron (governed + audited); lazy staleness on read as fallback. - Minor: some SQL built-ins gated (sqlite_version() not authorized); FTS5/bm25 and recursive CTE are authorized. 3. RESOLVED DECISION POINTS (all recommendations — ruling 667f1251): DP-MS1 normalized tags table + dedicated indexed status/kind/volatility columns (fixes /tags count bug). DP-MS2 revisions(entry_id, content, at) table for history, not content-string-append. DP-MS3 vector/semantic arm in v1 as optional binding, default off. DP-MS4 caller-provided classification at write time; LLM-classify is optional fallback binding. DP-MS5 exact-hash dedup baseline in v1; semantic dedup via binding later. DP-MS6 digests/auto-patterns dropped for v1 (tag stubs kept). DP-MS7 uncertainty-as-native (claim_tag + evidence_ref) in v1. DP-MS8 scheduled-tasks gatekeeper + lazy staleness fallback. DP-MS9 MINI_SPHERE_CONTRACT as separate child contract of SPHERE_GATEKEEPER_CONTRACT. DP-MS10 FTS5/BM25 (evidence, not a decision). 4. CONTRACT (pinned canonical, MINI_SPHERE_CONTRACT v0.1, SHA-256 B846EDB4..., status pinned draft, parent SPHERE_GATEKEEPER_CONTRACT, baseline live sphere db/schema.sql, evidence standard a5e10e10 as data): S1 Purpose: every workspace gets a memory/map layer as a blueprintable Gadget DO with SQLite. Contract-first. No MCP surface, no approval queue, no governed write-aperture. S2 Definitions: Mini-Sphere (gadget DO); workspace agent (consumer, Cap'n Web RPC, supplies classification at write time); optional binding (wired gatekeeper/AI, default off); scheduled-tasks gatekeeper (scheduler not approver); claim tag (VERIFIED/INFERRED/UNKNOWN). S3 Surface (direct RPC): Reads recall(query,{topK?,tag?,kind?,hops?,full?}), listRecent({n?,tag?}), getEntry(id), connections(id), graphView({seedIds,hops}), getTags(), getCount(), getStats(), getBrief(). 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 only): runStalenessPass({limit}). S4 Data model: entries(id PK, content, source, created_at, updated_at, recall_count, importance_score, claim_tag, evidence_ref, status, kind, volatility) with status/kind/volatility dedicated indexed columns; tags(entry_id, tag, PK(entry_id,tag)) normalized; edges(src,dst,type,weight,provenance,metadata,created_at,updated_at, UNIQUE(src,dst,type)) with 8 closed kind-gated types (relates_to symmetric canonicalized by id order, supersedes, caused_by, decided episodic-only, about_person, part_of_project, follows episodic-only, document_of); revisions(entry_id, content, at) for history; fts USING fts5(content) BM25; entries.content_hash for exact dedup. Provenance in {explicit, inferred, system}. S5 Retrieval (scores recomputed per request, no result cache): temporal query rewrite to queryUsed; prefilter status/kind/volatility + tags + created_at; keyword arm FTS5 MATCH + bm25 + ORDER BY rank; graph hops recursive CTE BFS depth 0-3 fanout<=8/node maxNodes50 score=seed*0.6^hop*edgeWeight; fusion 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 4000 chars tail 400 total 12000 full=1 bypasses; hydration drops auto-pattern + deprecated. Optional vector arm (default off): embedding binding cosine in JS over candidate set, fuses into RRF. S6 Writes & classification: workspace agent supplies kind/volatility/status/importance/claimTag/evidenceRef at write time. capture returns stored{id}/blocked{matchId} (hash dedup)/merged|replaced{id}. Optional LLM binding (default off): classify fallback, semantic dedup 0.95/0.85, auto-linking >=0.78, contradiction detection, digests, auto-patterns. S7 Maintenance: scheduled-tasks gatekeeper fires runStalenessPass({limit}) on a cron (narrow named method, least-privilege, audited); lazy staleness on read fallback. No self-alarms. Out of v1: digests/auto-patterns (tag stubs kept). S8 Out of scope: MCP surface; approval queue; gatekeeper write-aperture; ingestUrl/crawl/document-extraction; cross-workspace traversal; live queries; SurrealDB/VPS. S9 Uncertainty as native schema: claim_tag + evidence_ref real columns; a5e10e10 as data not convention. S10 Amendment: PRs to int_contracts via gatekeeper-github; version bump, re-pin, verbatim duplication, evidence snapshot. Conflicts reported, never improvised. S11 Name: MINI_SPHERE_CONTRACT registered per NAMING_CONTRACT; parent SPHERE_GATEKEEPER_CONTRACT. 5. DELIBERATE DEVIATIONS (record, do not carry over): (1) normalized tags + dedicated columns fixes /tags count bug; (2) revisions table cleaner than content-string-append; (3) pluggable retrieval arms, zero-binding default strong; (4) uncertainty-as-native implements v2 vision sphere lacks; (5) no chunking without binding; (6) caller-provided classification replaces post-write LLM classify. 6. BUILD PLAN (phased): Phase 0 bootstrap real gadget (use spike server.js as storage scaffold; stand up S4 schema with CREATE TABLE IF NOT EXISTS; robust toRows helper). Phase 1 core surface no bindings: writes capture (hash dedup + caller classification + claim_tag/evidence_ref), append (revisions), update, setStatus, forget, link (kind-gated, symmetric relates_to canonicalization, UNIQUE upsert max(weight)), unlink; reads getEntry, listRecent, connections, getTags (normalized trivial counts), getCount, getStats, getBrief (pure SQL); graphView (recursive CTE hops). Phase 2 retrieval pipeline: FTS5 keyword arm; temporal rewrite; prefilter; recursive-CTE hops; RRF fusion; rerank time-decay/MMR; snippet budgeting; recall wiring returning queryUsed. Phase 3 client UI: search/recall box, recent list, entry view with connections, graph view, capture form with kind/volatility/status/claimTag fields; responsive; realtime via Cap'n Web subscription optional. Phase 4 optional bindings (default off): embedding/vector arm semantic recall + dedup + auto-linking; LLM binding classify fallback + digests + auto-patterns. Wire only when a binding exists. Phase 5 scheduled maintenance: runStalenessPass (regex volatility heuristic, no LLM) + lazy staleness on read; wire scheduled-tasks gatekeeper (once available) to fire runStalenessPass on a cron via SCHEDULED_TASKS binding in creation manifest. OPEN see S7. Phase 6 governance close-out: register MINI_SPHERE_CONTRACT in name registry (NAMING_CONTRACT S6.3); ratify to canonical at Mike's word (currently pinned draft); publish as blueprint (goal: every workspace gets Mini-Sphere by default). 7. OPEN ITEMS: (1) Scheduled-tasks gatekeeper — the actual scheduler still needs locating/wiring. In the originating workspace the connection resolved to the MikeSphere memory MCP server (sphere v2 MCP surface), NOT a scheduler (no scheduling tool in catalog). In the new workspace identify the real scheduled-tasks gatekeeper (likely a separate server behind control-internal-portal.docuclear.ai) and connect it specifically. Only specified-but-not-demonstrated item (S7). (2) Name registry registration of MINI_SPHERE_CONTRACT. (3) Ratification to canonical (Mike's call). 8. BOOTSTRAP IN NEW WORKSPACE: (1) Connect SPHERE (ambient sphere memory); recall/getEntry the IDs in section 1 to pull the full design, contract, ruling entries. (2) Connect CONTEXT (docuclear-evidence); read /contracts/MINI_SPHERE_CONTRACT@0.1.md from collection c2f7ca03-a02c-4f3c-bf31-2a938b8b56e2 to get the byte-identical canonical contract; verify against pin B846EDB4DB3F1F6D3E30534974D30ECCE59F1F9FC6D940E151627FB2D18D60F7. (3) Create the Mini-Sphere gadget; build per section 6; re-run the spike (section 2) first to re-confirm FTS5 + recursive CTE in that workspace. (4) Locate & connect the real scheduled-tasks gatekeeper for the S7 maintenance spike. LINKS: design 03005dfe, contract c51653de, ruling 667f1251, work item 9c51aced, substrate 3e1f9f20, boundary 2144b79b, vision cf00a760, gatekeeper-family 6ed41ea6, evidence standard a5e10e10.
Tags: docuclear, mini-sphere, plan, handoff, transfer, contract, design, spike, project:docuclear, status:canonical, volatility:durable, duplicate-candidate, kind:semantic — Source: mcp — 2026-09-06 18:37:05 UTC