What it is

AI agents forget. Every session starts from zero, and when teams bolt on "memory" it is usually a vector store that keeps everything forever, has no idea who is allowed to see what, and slowly fills up with stale or contradictory facts that nobody owns. Enterprises can't put that in front of real decisions.

The Long-term Memory Service is the persistent memory layer that agents plug into over MCP. It is the runtime half of the Semantic Context Knowledge Graph: the knowledge graph supplies the business context, and this service keeps that context — plus everything agents learn while working — governed, current, and retrievable across sessions, agents and teams.

The idea is borrowed from cognitive science (the CoALA framework for language agents). The agent keeps its own working memory; the service persists the other three kinds:

  • Episodic — what happened: events, meetings, decisions, agent trajectories.
  • Semantic — what is true: ontology-bound facts and entities.
  • Procedural — how to do things: playbooks and SOPs (declarative documents only, never executable code).

Agents use five verbs: recall, remember, reflect, consolidate and lint. New experiences land as episodic notes. As a note is reused and corroborated by independent sources, it gets proposed for promotion into the semantic layer — the way the brain moves memories from the hippocampus to the cortex. Memory that isn't used fades in ranking, but nothing is ever deleted automatically, so the full history stays auditable.

What makes it enterprise-grade rather than a toy:

  • Permission-aware recall. Every query is filtered by the caller's identity before ranking. An agent never sees, counts, or infers a page it isn't allowed to read.
  • Provenance on everything. Every memory records who or what wrote it, so an agent can tell "the policy says X" from "a candidate's résumé claims X".
  • Governed writes. Logging an experience is automatic; changing facts is validated; changing the schema always needs a human.
  • Files first. The source of truth is plain markdown in git, readable and editable by people. Every database is a rebuildable index on top of it, so there is no lock-in and no data migration when storage is swapped.

Status: the architecture and technical design are complete and have been through an adversarial review (23 findings resolved). Implementation follows a phased, evidence-gated plan, where each capability ships only once it passes its own quality bar on real data.

Architecture

Three cooperating pieces:

  • cg — compiler/CLI. Compiles one declarative manifest (context-graph.yaml) into a working memory layer: file substrate, indexes and the memory API. How complete the manifest is decides how much gets built — docs only, then ontology, then live data bindings, then governance.
  • cgd — memory daemon (data plane). One process per memory layer, running in the customer's environment or on a laptop. It serves the five verbs over MCP, is the single writer for all changes, and runs the self-maintaining lifecycle loop: refresh → resolve → enrich → curate → learn.
  • Control plane. Fleet management, upgrades, SLO monitoring and a human escalation console. It connects outbound-only and sees metadata only — customer knowledge never leaves their environment.

Storage: two durable tiers, everything else derived. Git holds authored knowledge (pages, ontology, URIs); source systems hold operational data, which the graph projects through bindings. Vector, full-text, graph and score stores are disposable projections that can be rebuilt with one command. The default zero-infra profile is git + SQLite (sqlite-vec, FTS5) + embedded Kùzu in a single process. It scales out per store to pgvector/Qdrant, OpenSearch/Vespa or an RDF triplestore without migrating any data.

Recall pipeline:

  1. ACL pre-filter pushed into every index query (never post-filtered).
  2. Up to four candidate lists: vector ANN, BM25, graph traversal, and a journal overlay so an agent can immediately read what it just wrote.
  3. Reciprocal Rank Fusion of those lists.
  4. Salience modulation — a floor guarantees that a perfect match is never fully suppressed.
  5. A small exploration slot so buried knowledge can resurface.
  6. Assembly: results with snippet, provenance, freshness (as_of / stale), ACL-filtered citations, and a gap report listing the parts of the question with no visible support.

Memory lifecycle: captured → proposed → consolidated. Promotion requires high salience, no recent contradictions, and at least two independent sources. A single source can never manufacture confidence. Unused memory decays to "cold", which means it is excluded from default recall but still explicitly queryable.

Details

Memory API (MCP, versioned cg.v1):

  • recall(query, top_k, include_cold, as_of, filters) — ranked results with provenance, freshness, citations and gaps.
  • remember(page, idempotency_key) — append an episodic memory. Idempotent for 24 hours, so agent retries can't create duplicates.
  • reflect(scope) — synthesize higher-level insights across episodes and return them as proposals with citations.
  • consolidate(proposal_id) — validate a proposal against the ontology and commit it, queue it for review, or escalate it.
  • lint(scope) — find contradictions, orphans, stale, cold and gap pages, and apply fixes.

Salience model (ACT-R based): S = 0.5·activation + 0.3·corroboration + 0.2·trust.

  • Activation uses ACT-R base-level learning with a 32-entry ring buffer, so it needs constant memory per page.
  • Corroboration counts only origin-distinct sources: copy-pasted facts count once.
  • Trust is a PageRank over the source-citation graph.
  • The weights are treated as hypotheses and tuned under a permanent offline A/B harness.

Governance — write-tier ladder:

  • Tier 0: episodic append — automatic, provenance-stamped.
  • Tier 1: semantic fact — validated with SHACL and auto-committed only once consolidation precision reaches 0.95 or higher.
  • Tier 2: procedural page — opens a review branch.
  • Tier 3: ontology schema — always requires human approval and is never automated.

Security and compliance:

  • OIDC identity, with permissions inherited from data catalogs (Unity Catalog, Lake Formation, Ranger). Authorization fails closed.
  • Graph paths through nodes the caller can't see are pruned, so no relationship leaks through a hidden node.
  • A hash-chained, append-only audit log records every read and write.
  • Legal erasure (GDPR) is the only true delete. It is human-invoked and leaves a tombstone.

Performance targets:

  • recall: p95 under 500 ms at 100k pages.
  • remember acknowledgement: p95 under 150 ms, durable on acknowledgement.
  • Write-to-recall visibility: 5 seconds or less.
  • Availability: 99.9%.
  • Full rebuild from git: 30 minutes or less at 100k pages.

Integration: the service fills the long-term "Store" slot in agent frameworks. Conversation history stays with the framework's checkpointer, and working memory stays in the agent. A LangGraph reference integration is written; CrewAI, the Claude Agent SDK and raw MCP guides are planned.

Deployment: same binary everywhere — local (free), BYOC in the customer's VPC (enterprise), and a planned hosted multi-tenant cloud with usage-based pricing for agent developers.

Stack: Python 3.12, MCP, git, SQLite/sqlite-vec/FTS5, Kùzu, RDF/SHACL (rdflib, pyshacl) and OpenTelemetry.