Memory Backends — Integration Guide

Licensed commands. Every CortexBuild command except auth and the host-invoked hook requires a valid licence. If you see license required, run cortexbuild auth activate --key <token> (or cortexbuild auth refresh if a lease simply lapsed) and try again. --help always works.

CortexBuild can optionally persist long-term agent memory over the artefacts it already produces (.cortexbuild/analysis/structural.json, .cortexbuild/analysis/GRAPH_REPORT.md, .cortexbuild/recurrence-ledger.yaml). Memory is opt-in and additive: the files in .cortexbuild/ remain the source of truth; memory is a queryable cache seeded from them.

---

Decision flow — pick a backend in under 60 seconds

Do you want cross-session memory at all?
│
├─ No  → do nothing. Agents read .cortexbuild/ files directly. (default)
│
└─ Yes → Do you need graph / temporal reasoning over the memory?
         │
         ├─ No  → mem0            (recommended default; in-process, Python)
         │
         └─ Yes → Already run Neo4j?
                  ├─ Yes → graphiti   (temporal knowledge graph)
                  └─ No  → cognee     (Python KG, no Neo4j required)

Already operate a Letta server?   → letta
Want zero new dependencies today? → MCP filesystem server (baseline)

Target: a developer with zero context has working memory in under 5 minutes by following the mem0 section below.

---

Supported backends

mem0 — recommended default

Python-native, in-process, Apache-2.0. Maps 1:1 onto the CortexBuild adapter.

Install

pip install "cortexbuild-core[memory]"

Enable + seed

# Seed memory with this repo's structural + graph artefacts
cortexbuild init run . --with-memory

# Mirror ledger transitions into memory (opt-in, best-effort)
export CORTEXBUILD_MEMORY=1
cortexbuild ledger set-status my-finding implemented

Usage

Enable it (--with-memory and CORTEXBUILD_MEMORY=1), and CortexBuild seeds it from your .cortexbuild/ artefacts automatically. Your own code can query it through a small, documented Python interface for adding and searching records.

• Pick when: you want simple, durable recall with no external services.
• Avoid when: you specifically need graph/temporal queries (see cognee/graphiti).

---

cognee — knowledge-graph alternative

Python-native ECL (extract → cognify → load) pipeline with pluggable vector + graph stores. Apache-2.0.

Install

pip install cognee

Wrap a cognee-backed client in an object exposing add / search / update / delete / get_all and pass it through the same adapter interface the other backends use.

• Pick when: your workflows are knowledge-graph-heavy and you want reasoning over relationships, not just nearest-neighbour recall.
• Avoid when: you only need lightweight recall — mem0 is simpler.

---

letta (ex-MemGPT) — if you already run Letta

Self-editing memory + agent runtime. Apache-2.0. Server/runtime model.

Install

pip install letta

• Pick when: you already operate a Letta server and want CortexBuild to reuse it.
• Avoid when: you don't want to run a separate server/runtime — CortexBuild already owns orchestration, so letta's runtime overlaps ours.

---

graphiti — if you already run Neo4j

Best-in-class temporal knowledge graph. Apache-2.0. Requires Neo4j.

Install

pip install graphiti-core
# plus a running Neo4j instance (bolt://...)

• Pick when: you already have Neo4j and want temporal graph memory that pairs with CortexBuild's dependency graph.
• Avoid when: you don't want to stand up Neo4j — use cognee for a Python-only KG.

---

MCP filesystem server — zero-dependency baseline

Works today with no extra Python dependency: an MCP filesystem server exposes the .cortexbuild/ directory to any MCP-capable client as a read surface.

Install

npx -y @modelcontextprotocol/server-filesystem ./.cortexbuild

Wire-up (MCP client config)

{
  "mcpServers": {
    "cortexbuild-memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "./.cortexbuild"]
    }
  }
}

• Pick when: you want something working immediately with zero install of a memory library, or your agent client speaks MCP.
• Avoid when: you need semantic search / ranking — this is plain file access, not vector recall.

---

Comparison at a glance

Backend	Install	Runtime	External infra	Graph memory	Pick when
mem0	pip install "cortexbuild-core[memory]"	In-process	None	Optional	Default; simple durable recall
cognee	pip install cognee	In-process pipeline	Pluggable	✅	KG-heavy reasoning, no Neo4j
letta	pip install letta	Server	Server + DB	Partial	You already run Letta
graphiti	pip install graphiti-core	Library	Neo4j	✅ (temporal)	You already run Neo4j
MCP filesystem	npx … server-filesystem	Node MCP server	None (Node)	❌	Zero-dep baseline / MCP clients

---

How it fits together

• Files win. Memory is seeded from .cortexbuild/ artefacts and is fully rebuildable. On any conflict, the committed files are authoritative.
• One interface, swappable backends. Every backend exposes the same add / search / update / delete interface. mem0 is the default implementation; the others slot behind the same contract.
• Opt-in everywhere. No default install pulls in a memory library; CI is unaffected. Enable per-repo with --with-memory and CORTEXBUILD_MEMORY=1.

---

Shared / hosted memory — egress security boundary

When memory is shared across tools via the hosted backend, every write or erase passes through a single fail-closed redaction gate before any byte can leave the machine:

• Redaction on the normal path. Every free-text field that egresses — text, source, and tool — is run through the central redactor; a secret-shaped record id is replaced with a deterministic id derived from the redacted content hash. The repo_namespace is the cross-tool sharing key, so it is validated (must be a canonical repo: identity) rather than redacted — and a namespace that contains a secret-shaped token is refused (fail-closed) instead of silently mutated.
• Provenance origin is required, fail-closed. The caller MUST pass the TRUE provenance origin, derived at record-creation time from where the content came from. If origin is absent / unknown / unclassified, the hosted write is refused (fail-closed to proprietary). The boundary never guesses an origin, and consent never relaxes this rule for proprietary/unknown rule text.
• Consent is read fresh every write. Consent is loaded from disk on each write; deleting consent.json (revocation) causes the next write to be refused.
• GDPR erasure is real. A shared learning can be erased by record_id or by its redacted content_sha256, so an operator on a different tool — who has only the content, not the original id — can still erase it.

What this boundary covers

These controls prevent accidental egress of PII, secrets or proprietary rule text on the normal paths. They are not a sandbox against a machine an attacker already fully controls at the code-execution level -- no in-process safeguard can be, in any language -- so this boundary should be understood as hardening the normal path, not as a defence against a fully controlled host.