Memory
Decision (2026-08-19): Sphere SurrealDB build adopts the Spectron-inspired model via the IntelligentRAG plan (entry d78ecf2c). Topology: one SurrealDB per container deployment, NS sphere with DB global (IntelligentRAG = global memory) + DB ws_<id> per workspace (isolated). OpenCode is the curator/owner of the database — the librarian — and ALL writes go through it executing the three graph-stored procedures (ingest, retrieve, reconcile); reconciliation is the single write path. Cross-DB boundary crossed by provenance-as-data (workspace id + entry id), not record links; promotion workspace->global is a reconcile operation. Schema v2 drafted as sphere_schema_v2.surql: merges v1 workspace skeleton (threads/turns/runs/steps/documents/blocks/workflows/secrets) with Spectron memory semantics (six categories, tri-temporal clocks, trust+confidence calibration, entity/topic/keyword graph, traces as memory, explicit uncertainty, tiered retrieval T1-T4 with supersede-invalidated response cache). Deferred: PageRank, geographic recall, NotebookLM-style generate.
[Update Sep 2, 2026]: Update (Sep 2, 2026, ~11:12pm BST): TIMING DECISION — SurrealDB is LATER, deferred with explicit activation triggers rather than a date. Rationale: (1) the sphere is production-ready TODAY on D1/KV/Vectorize/R2 + DOs (1502/1502 tests, W4P-verified, Secrets Store integrated) and the recorded critical path is first customer → redaction → semantic classification — SurrealDB unblocks none of them; (2) the Sep 2 architecture (headless sphere, OS interaction layer, gatekeeper trust boundary, callsign coordination) changed the requirements surface — notably, OS context-git / Artifacts now covers part of what a SurrealDB document store might have done, so the storage boundary needs deciding BEFORE building; (3) too many concurrent bets is how solo-founder projects die — today's discipline was one decisive gate at a time.
ACTIVATION TRIGGERS (any one fires the build): (a) the compliance/graph product line reactivates — the compliance engine's canonical home was always SurrealDB (f1fab026) and graph versioning is its core need; (b) recall quality / cross-entity traversal becomes the visible product limitation on the D1+Vectorize substrate; (c) the OS context-git boundary decision is made AND leaves graph-memory semantics unassigned.
WHY LATER IS CHEAP: IntelligentRAG is a LIVE SurrealDB reference deployment (intelligent-rag.mike-c79.workers.dev, since Jul 17) — the build is an adaptation, not greenfield; schema v2 is already drafted (sphere_schema_v2.surql); the rebuild-vectors utility pattern proves the state-migration path. OPEN TENSION to resolve at build time: this entry says 'one SurrealDB per container deployment' but the ingestion economics decision (72cafb0f) forbids per-customer containers — the schema's NS sphere / DB ws_<id>-per-workspace design already points at a shared SurrealDB service with per-workspace DBs, which is the likely resolution.
[Update Sep 4, 2026]: [Update Sep 4, 2026]: TRIGGER FIRED (Sep 4, 2026, ~2:30pm BST — Mike, with Perplexity). Trigger list AMENDED with (d): SPHERE ROLE PROMOTION — the sphere's role promoted from memory/index store to (1) the agent NAVIGATION SUBSTRATE ('sphere is the map': tells the agent what exists, how it works, what was decided, and where base authority lives — demonstrated live this session: Perplexity grounded entirely via recall + link graph, no files) and (2) a PLATFORM CAPABILITY under the three-layer boundary ruling (2144b79b). Role promotion makes the requirements graph-shaped: typed relations, traversal, lifecycle status, fused search, per-trust-domain isolation. TRIGGER (d) RULED FIRED: switch from the current spheres to a SurrealDB memory substrate as THE platform sphere capability.
MIKE'S RULINGS: (1) TOPOLOGY — first build proves operational on Mike's UK VPS (via tunnel) or SurrealDB Cloud free instance: build over infra. Preferred production topology = INSTANCE PER CUSTOMER, VPS-hosted at low cost, UK residency; final production topology DEFERRED. Note: this reopens this entry's 'shared service with per-workspace DBs' lean — VPS hosting changes the economics; 72cafb0f forbids per-customer CF containers, not VPS instances. (2) BUILD FOR BEST — no carried-over limitations from vendor sphere or docuclear-sphere; migration can be manual; schema v2 (sphere_schema_v2.surql) is a draft starting point, not a constraint; the MCP tool surface becomes a VERSIONED contract (SPHERE_GATEKEEPER_CONTRACT v2 may supersede v1). (3) MVP BOUNDARY (clarified, agreed): substrate switch is platform-plane work; MVP feature scope unchanged; feature 5 (policy tables) stays D1 UNLESS the substrate is operational before its build starts — then it goes straight to graph, no D1 throwaway. Two substrates coexist during transition, named not drifted. (4) QUEUE — substrate build becomes the decisive gate; factory adoption mechanics deprioritised (current-sphere deployment pipeline is no longer the near-term need); vibesdk PRODUCT loop (signup-site dogfood, first-customer unblock) UNCHANGED.
Tags: sphere, surrealdb, spectron, intelligentrag, architecture, decision-record, schema, opencode, build-plan, kind:episodic, status:canonical — Source: mcp — 2026-08-19 06:31:13 UTC