Canonadr

ADR-2026-09-03-03 — Memory provider abstraction and the L1–L8 level model

Status: APPROVED — 2026-09-03 (founder ruling)
Supersedes: the stage-based "L1–L8 promotion" framing in the Canonical Product Spec and G-10's earlier note

Ruling

  1. Memory providers (Mem0, Zep, Graphiti, Letta) are provider-based intelligence/memory engines underneath Spine Core. They are never a second memory authority.
  2. Spine owns meaning. Business Context, Work, Decisions, Actions, Outcomes, Evidence, KPIs, Risks, Governance, canonical relationships, tenant ownership, auditability, reconciliation.
  3. 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.
  4. L1–L8 are memory LEVELS BY KIND — not storage locations and not promotion stages:
L1  Interaction
L2  Working Context
L3  Episodic Memory
L4  Semantic Context
L5  Evidence
L6  Governed Knowledge
L7  Canonical Business State
L8  Reconciled Truth

Provider usage is an implementation decision: L1–L4 are served by the
Memory Fabric (six memory kinds: contextual, semantic, episodic,
temporal, graph, working) fed by the Context Projection from Spine
Core's canonical business context; promotion/validation promotes material
to L5–L6 (Spine-governed memory); L7–L8 exist only in Spine Core.
Replacing Zep with Mem0 must not change the boundary — the business
meaning lives in Spine's canonical model, and providers carry contextual
copies that never become authoritative.

  1. MemoryProvider is an interface with adapters (Mem0, Zep, Graphiti, Letta,
    NativeSpine). The rest of the system never knows which is active.
  2. Canonical memory stays native. spine_context, spine_work,
    spine_decision, spine_action, spine_outcome, memory_evidence,
    memory_knowledge, memory_risk, memory_signal, memory_forecast,
    memory_kpi. External providers are index/retrieval/extraction substrates
    over that data — never the system of record.

AI rented. Memory owned. Semantic memory infrastructure can be rented.
Canonical business memory remains owned by Spine.

  1. Mem0/Zep/Letta appear in the Provider Fabric, never in the user's
    conceptual model.     The user experiences "Spine remembers."

  2. Memory records carry meaning AND business context, not metadata —
    content + business_context (type/id: customer_renewal, objective_id,
    kpi_id, work_id), entity_refs, work_id, evidence_refs, temporal validity,
    confidence, importance, sensitivity, provenance (see contract doc 01).
    Example: "Acme renewal is at risk because of the unresolved billing
    dispute" travels WITH {type: customer_renewal, customer_id: acme, objective_id: renewal_q3, kpi_id: net_retention, work_id: renewal_acme_2026} and evidence refs (zendesk_ticket_1842,
    slack_thread_9281) — so Mem0/Zep/Graphiti can retrieve the memory in
    context and understand relationships: Customer → Account → Renewal →
    Objective → KPI → Risk → Evidence → Work → Decision → Action → Outcome.

Consequences

  • The 19 memory tables are built against THIS boundary: native Spine tables
    for L5–L8; provider adapters serve L1–L4 retrieval over them.
  • MemoryProvider interface (packages/memory) is the only sanctioned access
    path for provider-backed memory. No direct Mem0/Zep SDK calls elsewhere.
  • The promotion pipeline (source → extraction → candidate fact → evidence →
    validation → governance → Spine canonical record) is a core primitive of the
    contract, not a per-feature afterthought.
  • Agentic Home consumes context packages, not chat history. Core assembles:
    Work → Business Context → Relevant Memory → Evidence → Current State →
    KPI/Risk → Available Actions → Governance. The Twin reasons over that
    package (e.g. the Acme renewal package: work, $180K ARR context, billing
    dispute state, GRR KPI 91.8% vs 94% target, risk trajectory, memory of past
    incidents, evidence refs, proposed work with Finance approval required).
  • G-10 reframed: the register's stage model note is superseded by this level
    model.