{"slug":"canonical/adr/ADR-2026-09-03-03-memory-provider-abstraction-and-l1-l8-level-model","title":"ADR-2026-09-03-03 — Memory provider abstraction and the L1–L8 level model","section":"canonical","sectionLabel":"Canon","status":"canon","type":"adr","path":"canonical/adr/ADR-2026-09-03-03-memory-provider-abstraction-and-l1-l8-level-model.md","bytes":4721,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\n**Status:** APPROVED — 2026-09-03 (founder ruling)\n**Supersedes:** the stage-based \"L1–L8 promotion\" framing in the Canonical Product Spec and G-10's earlier note\n\n## Ruling\n\n1. **Memory providers (Mem0, Zep, Graphiti, Letta) are provider-based intelligence/memory engines underneath Spine Core.** They are never a second memory authority.\n2. **Spine owns meaning.** Business Context, Work, Decisions, Actions, Outcomes, Evidence, KPIs, Risks, Governance, canonical relationships, tenant ownership, auditability, reconciliation.\n3. **Spine owns the canonical business context; memory providers must ingest, preserve, retrieve, and reason over that context.** Providers are not dumb embedding stores — every memory carries its business context (entity refs, business_context type/id, work_id, objective_id, kpi_refs, evidence_refs, temporal validity, confidence, importance, sensitivity, provenance) so providers can retrieve memory **in context**, not as isolated sentences. On top of that they provide: embeddings, semantic retrieval, conversation memory, temporal retrieval, graph traversal, summarization, episodic memory, working context, agent state.\n4. **L1–L8 are memory LEVELS BY KIND — not storage locations and not promotion stages:**\n\n```text\nL1  Interaction\nL2  Working Context\nL3  Episodic Memory\nL4  Semantic Context\nL5  Evidence\nL6  Governed Knowledge\nL7  Canonical Business State\nL8  Reconciled Truth\n```\n\n   Provider usage is an implementation decision: L1–L4 are served by the\n   **Memory Fabric** (six memory kinds: contextual, semantic, episodic,\n   temporal, graph, working) fed by the **Context Projection** from Spine\n   Core's canonical business context; promotion/validation promotes material\n   to L5–L6 (Spine-governed memory); L7–L8 exist only in Spine Core.\n   Replacing Zep with Mem0 must not change the boundary — the business\n   meaning lives in Spine's canonical model, and providers carry contextual\n   copies that never become authoritative.\n\n5. **MemoryProvider is an interface with adapters** (Mem0, Zep, Graphiti, Letta,\n   NativeSpine). The rest of the system never knows which is active.\n6. **Canonical memory stays native.** `spine_context`, `spine_work`,\n   `spine_decision`, `spine_action`, `spine_outcome`, `memory_evidence`,\n   `memory_knowledge`, `memory_risk`, `memory_signal`, `memory_forecast`,\n   `memory_kpi`. External providers are index/retrieval/extraction substrates\n   over that data — never the system of record.\n\n> **AI rented. Memory owned.** Semantic memory infrastructure can be rented.\n> Canonical business memory remains owned by Spine.\n\n7. **Mem0/Zep/Letta appear in the Provider Fabric, never in the user's\n   conceptual model.** The user experiences \"Spine remembers.\"\n\n8. **Memory records carry meaning AND business context, not metadata** —\n   content + business_context (type/id: customer_renewal, objective_id,\n   kpi_id, work_id), entity_refs, work_id, evidence_refs, temporal validity,\n   confidence, importance, sensitivity, provenance (see contract doc 01).\n   Example: \"Acme renewal is at risk because of the unresolved billing\n   dispute\" travels WITH `{type: customer_renewal, customer_id: acme,\n   objective_id: renewal_q3, kpi_id: net_retention, work_id:\n   renewal_acme_2026}` and evidence refs (zendesk_ticket_1842,\n   slack_thread_9281) — so Mem0/Zep/Graphiti can retrieve the memory in\n   context and understand relationships: Customer → Account → Renewal →\n   Objective → KPI → Risk → Evidence → Work → Decision → Action → Outcome.\n\n## Consequences\n\n- The 19 memory tables are built against THIS boundary: native Spine tables\n  for L5–L8; provider adapters serve L1–L4 retrieval over them.\n- `MemoryProvider` interface (`packages/memory`) is the only sanctioned access\n  path for provider-backed memory. No direct Mem0/Zep SDK calls elsewhere.\n- The promotion pipeline (source → extraction → candidate fact → evidence →\n  validation → governance → Spine canonical record) is a core primitive of the\n  contract, not a per-feature afterthought.\n- **Agentic Home consumes context packages, not chat history.** Core assembles:\n  Work → Business Context → Relevant Memory → Evidence → Current State →\n  KPI/Risk → Available Actions → Governance. The Twin reasons over that\n  package (e.g. the Acme renewal package: work, $180K ARR context, billing\n  dispute state, GRR KPI 91.8% vs 94% target, risk trajectory, memory of past\n  incidents, evidence refs, proposed work with Finance approval required).\n- G-10 reframed: the register's stage model note is superseded by this level\n  model.\n"}