Memory Overview
Memory (ai-memory.svc) owns the platform’s interaction memory — the durable record of what happened in conversations between people, agents, and bots, and the knowledge distilled from them. It gives agents and bots long-term memory: what a user said last week, what they prefer, what was decided.
The dividing line is provenance: Memory owns memory derived from interaction. Knowledge ingested from external documents belongs to RAG. Memory does not depend on RAG — they sit on opposite sides of that line.
The three tiers
Section titled “The three tiers”Memory abstracts interactions up a ladder — the more abstracted a memory, the longer it lives:
| Tier | What | Lifetime |
|---|---|---|
| Sessions & Messages | The verbatim interaction stream, append-only — the source of truth | Shortest (raw; aged out after distillation) |
| Episodes | Salient events distilled from sessions (a request, a decision, a preference signal), each with an importance score and an embedding | Medium |
| Facts | Durable semantic knowledge (“prefers terse replies”), bitemporal and abstracted | Longest |
Three paths
Section titled “Three paths”Memory is split into three independent paths so writes stay cheap and reads stay fast:
- Ingest (write) — a cheap, durable append. No LLM, no embedding inline; it returns immediately and emits a lifecycle event. Recording a conversation never blocks on analysis.
- Consolidate (background) — the AI-driven work, off the hot path, in latency tiers: near-real-time embedding/indexing, session-close summarization + episode/fact extraction, and a nightly deep pass that merges facts and decays importance.
- Recall (read) — fast, ranked, budget-fit. It blends the most recent raw turns (read straight from the session store, so the latest message is never lost to a lagging pipeline) with semantically relevant episodes and facts.
Recall ranks by a relevance × recency × importance triad, scaled by how close the memory’s scope is to the caller, and fits the result to a token budget.
Scoping
Section titled “Scoping”Two levels:
- CPET (customer : product : environment : tenant) is the hard wall — mandatory on every operation and filtered on every query, so cross-tenant access is impossible by construction. The semantic index is partitioned by CPET.
- Scope is the opaque soft structure inside the wall — a subject (an agent or a human), a team, or an org unit. Memory tags and matches scopes but never interprets them; a persistent agent owns one or more scopes as its private memory, and a team is just another scope.
Authorization arrives signed with the request (a scope claim) — Memory verifies it and never calls out to an identity service to fetch permissions.
Facts are bitemporal
Section titled “Facts are bitemporal”A fact is never overwritten. When a confident contradiction arrives, the old fact’s validity is closed (valid_to = now) and a new one is recorded — so Memory can answer both “what is true now” and “what did we believe on this date”. Repeating an assertion reinforces its confidence and merges provenance rather than duplicating it.
Governance
Section titled “Governance”Forgetting is first-class, with two distinct drivers:
- Retention — importance-weighted decay and TTL sweeps age out old raw messages (never before their episodes are safely extracted).
- Right-to-forget — a provenance-propagated cascade delete that fails loudly (never silently partial) and is audited.
Users can also edit their own memory (taking precedence over machine-extracted facts), set per-scope exclusions (“don’t remember X”), and rely on sensitive-attribute suppression.
Where things sit
Section titled “Where things sit”| Item | Value |
|---|---|
| Binary | ai-memory.svc |
| Boot config | .ai-memory.yaml (-f) |
| Storage | per-tenant sessions/episodes/facts via the data layer (SQLite for dev, Postgres for production) |
| Models | embedding + consolidation models via the AI gateway |
Continue with:
- API — write, recall, facts, and governance
- Operations — bootstrap, consolidation, retention
- Error Codes