Core-Memory CLAUDE.md

CLAUDE.md — Core Memory

Canonical reference: docs/architecture_overview.md Phase completion state: docs/status.md Cleanup workstream: docs/cleanup-plan.md + docs/PRD/README.md Compatibility ledger: docs/compatibility_ledger.md

---

What this repo is

Core Memory is the causal memory layer for AI agents. It is not a vector search engine, not a graph database, and not a framework. It composes those things as pluggable tiers. The datastore, semantic index, and all framework integrations (MCP, PydanticAI, OpenClaw, LangChain, CrewAI, SpringAI) are adapters — none are first-party.

---

Guiding principle — engineering simplicity

There is a real risk that Core Memory becomes over-complex at the storage and retrieval layer. The danger is not that the project reduces to "a flat memory file plus semantic search" — it is that we solve several distinct problems at once and describe all of them as "memory."

The distilled question every feature must answer:

What must remain true across agents, sessions, and changing evidence that ordinary retrieval cannot reliably preserve?

A flat file and semantic search already cover 80–90% of practical value: preserving facts, preferences, decisions, and conventions; retrieving relevant prior context; maintaining project summaries; sharing team knowledge through Git; providing provenance through links; superseding old information with simple status fields; generating a current "working memory" document. A well-maintained MEMORY.md, event log, embeddings index, and periodic synthesis pass outperforms many elaborate memory systems.

That approach breaks — and Core Memory is justified — only where memory becomes contested, temporal, distributed, and action-relevant:

• Is this statement observed, inferred, assumed, or merely repeated?
• Was it true then, is it true now, and what caused it to change?
• Which source should dominate when memories conflict?
• Is this a user belief, an organizational policy, an agent conclusion, or an external fact?
• What did the system know at the moment a decision was made?
• Which agent altered the shared understanding, and on what evidence?
• Can a new agent inherit not just conclusions, but the constraints and reasoning boundaries around them?
• Can we safely revise a belief without silently rewriting history?