core-memory 1.1.0

Persistent causal agent memory with lossless compaction

Causal memory for AI agents.
Structured memory objects + causal trace over durable events — so agents can recall why, not just what.

Install · Fastest Paths · Service Mode · Current Status · Architecture · Public Surface · Contributing · Maintainers

---

Reviewer Quick Path

1. core-memory --root ./memory setup init
2. CORE_MEMORY_CANONICAL_SEMANTIC_MODE=degraded_allowed PYTHONPATH=. python3 examples/canonical_5min.py
3. PYTHONPATH=. python3 examples/proof_carry_forward.py
4. PYTHONPATH=. python3 -m eval.reviewer_quick_value_v2 --root ./memory --strict

Optional follow-up telemetry (proxy-style, not full strategy replay benchmark):

• PYTHONPATH=. python3 -m eval.dreamer_behavior_eval --root ./memory --since 30d
• PYTHONPATH=. python3 -m eval.longitudinal_benchmark_v2 --root ./memory --since 30d

Then use:

• docs/reviewers/start-here.md
• docs/contributor_map.md
• docs/canonical_surfaces.md
• docs/architecture_overview.md
• docs/integrations/ (OpenClaw / PydanticAI / SpringAI / LangChain / Neo4j shadow graph)

Current Status

• Canonical surfaces: process_turn_finalized / process_session_start / process_flush + search / trace / execute
• Adapter helper ingress: emit_turn_finalized(...) remains supported for bridge/integration adapters
• Compatibility surfaces: archived or non-primary docs/modules retained for migration/history only
• Experimental areas: optional adapters and evaluation harnesses that are useful but not yet hard product contract
• Not yet integrated: ideas/proposals not represented in canonical docs or adapter references are intentionally out of current contract scope

Product Contract (Plain English)

If you're new here, this is the shortest trust contract for what is stable now:

• Required (core product):
  • write memory with process_turn_finalized(...)
  • read memory with memory search|trace|execute (or Python equivalents)
• Recommended for most users:
  • keep CORE_MEMORY_CANONICAL_SEMANTIC_MODE=degraded_allowed on base installs
  • install core-memory[semantic] when you want strict semantic retrieval behavior
• Compatibility (supported, not primary):
  • direct MemoryStore workflows
  • legacy CLI aliases like recall ...
• Experimental / adapter-specific:
  • optional integrations and eval harnesses that are not listed as canonical surfaces

If a feature is not in this contract or docs/public_surface.md, treat it as non-primary.

30-second tier map (mandatory vs optional)

• Required
  • base install: pip install core-memory
  • canonical write boundary: process_turn_finalized(...)
  • canonical retrieval: memory search|trace|execute (or Python equivalents)
• Recommended
  • semantic extras: pip install "core-memory[semantic]"
  • strict semantic retrieval mode (CORE_MEMORY_CANONICAL_SEMANTIC_MODE=required) when you need hard semantic guarantees
• Compatibility (supported, not primary)
  • MemoryStore direct workflows
  • adapter helper ingress emit_turn_finalized(...)
• Experimental / optional extensions
  • Neo4j shadow adapter (visualization/inspection)
  • eval harnesses under eval/

Plain-English glossary for first-touch terms

• canonical semantic mode → strict semantic retrieval mode
• degraded_allowed → allow lexical fallback if semantic backend is missing
• companion service → optional HTTP service mode
• hydration → load source details after selecting retrieval results

---

Live Demo

Watch the Core Memory live demo on YouTube

---

What Is Core Memory?

Most agent memory systems store what happened. Core Memory stores why it happened.

It records structured memory events called beads — decisions, lessons, outcomes, evidence, context — and the causal links between them. When an agent asks “why did we change strategy?”, Core Memory retrieves a decision chain, not just keyword matches.

Why use it?

Approach	Failure Mode	Core Memory
Chat log replay	Context window explodes	Bounded rolling window with compaction
Vector similarity	“Similar” ≠ “relevant”	Semantic-first anchors + causal trace over explicit bead links
Tool call logs	No reasoning structure	Explicit bead → bead associations

Core local write flow has zero required runtime dependencies beyond Python. Query-based anchor lookup in canonical mode requires semantic backend support (or explicit degraded mode opt-in). Optional extras exist for HTTP service mode and integration-specific workflows.

---

Install

From PyPI

pip install core-memory

From source

git clone https://github.com/JohnnyFiv3r/Core-Memory.git
cd Core-Memory
python3 -m venv .venv
source .venv/bin/activate
pip install -U pip
pip install -e .

Optional extras

Semantic backend extras (recommended for canonical query path):

pip install "core-memory[semantic]"

If you want provider-backed semantic embeddings, install the matching client library in the same Python environment. For example, OpenAI-backed semantic retrieval needs:

pip install openai

HTTP companion service:

pip install "core-memory[http]"

PydanticAI adapter:

pip install "core-memory[pydanticai]"

Neo4j shadow graph adapter (visualization/inspection only):

pip install "core-memory[neo4j]"

Developer/test extras:

pip install "core-memory[dev]"

---

Fastest Paths

1) Smallest believable product path (5 minutes)

No adapters, no direct MemoryStore calls, canonical boundaries only.

core-memory --root ./memory setup init

# Base install path (no semantic extras)
export CORE_MEMORY_CANONICAL_SEMANTIC_MODE=degraded_allowed
python3 - <<'PY'
from core_memory import process_turn_finalized, memory_execute

root = "./memory"
process_turn_finalized(
    root=root,
    session_id="five-minute",
    turn_id="t1",
    user_query="What should we do about Redis timeouts?",
    assistant_final="Decision: increase pool size to 200.",
)
out = memory_execute(
    request={"raw_query": "why redis timeouts", "intent": "causal", "k": 5},
    root=root,
    explain=True,
)
print({
    "ok": out.get("ok"),
    "degraded": out.get("degraded", False),
    "result_count": len(out.get("results") or []),
})
PY

Expected output:

• ok: true
• a non-zero result_count
• degraded: true is acceptable in this base-install path

If you want strict canonical semantic mode instead:

pip install "core-memory[semantic]"
unset CORE_MEMORY_CANONICAL_SEMANTIC_MODE
python3 - <<'PY'
from core_memory import process_turn_finalized, memory_execute

root = "./memory"
process_turn_finalized(
    root=root,
    session_id="five-minute",
    turn_id="t1",
    user_query="What should we do about Redis timeouts?",
    assistant_final="Decision: increase pool size to 200.",
)
out = memory_execute(
    request={"raw_query": "why redis timeouts", "intent": "causal", "k": 5},
    root=root,
    explain=True,
)
print({
    "ok": out.get("ok"),
    "degraded": out.get("degraded", False),
    "result_count": len(out.get("results") or []),
})
PY

Source-checkout equivalent example script:

PYTHONPATH=. python3 examples/canonical_5min.py

2) Canonical Python runtime/retrieval path

from core_memory import process_turn_finalized, memory_execute

root = "./memory"

process_turn_finalized(
 root=root,
 session_id="s1",
 turn_id="t1",
 user_query="Why did Redis fail?",
 assistant_final="Decision: increase Redis pool to 200 to prevent exhaustion.",
)

out = memory_execute(
 request={"raw_query": "why redis", "intent": "causal", "k": 5},
 root=root,
 explain=True,
)

print(out.get("ok"), len(out.get("results") or []))

3) CLI retrieval surface

Once memory exists, canonical retrieval CLI is:

core-memory --root ./memory memory search --query "redis pool"
core-memory --root ./memory memory trace --query "why redis pool"
core-memory --root ./memory memory execute --request '{"raw_query":"why redis","intent":"causal","k":5}'

4) Compatibility store API (advanced / direct persistence)

MemoryStore remains available for direct persistence workflows and migrations, but it is not the primary canonical runtime path.

See:

• examples/store_compat_quickstart.py

---

Service Mode (SpringAI / HTTP)

For JVM, JS/TS-adjacent, or service-oriented architectures, run Core Memory as a companion HTTP service.

Start the service

python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[http]"
python3 -m core_memory.integrations.http.server

Equivalent startup command:

python3 -m uvicorn core_memory.integrations.http.server:app --host 0.0.0.0 --port 8000

Optional auth:

export CORE_MEMORY_HTTP_TOKEN="change-me"

Verify the service

curl http://localhost:8000/healthz

curl -X POST http://localhost:8000/v1/memory/execute \
 -H "Content-Type: application/json" \
 -d '{
 "request": {
 "raw_query": "why did we change strategy?",
 "intent": "causal",
 "k": 5
 },
 "explain": true
 }'

SpringAI write path

Send finalized assistant turns to:

• POST /v1/memory/turn-finalized

Minimum useful fields:

• session_id
• turn_id
• user_query
• assistant_final

Session lifecycle boundaries:

• POST /v1/memory/session-start (explicit session-start snapshot boundary)
• POST /v1/memory/session-flush (session-end flush boundary)
• GET /v1/memory/continuity (pure-read continuity payload; no implicit writes)

SpringAI runtime path

Preferred single-call endpoint:

• POST /v1/memory/execute

This is the best fit for service-oriented orchestration where a backend needs one deterministic memory call instead of multiple client-side routing steps.

See also:

• docs/integrations/springai/quickstart.md
• docs/integrations/springai/integration-guide.md
• docs/integrations/springai/api-reference.md

---

Integrations

Canonical ingress port

from core_memory import process_turn_finalized

Adapter/helper ingress remains available for bridge code:

from core_memory.integrations.api import emit_turn_finalized

Available integration surfaces

• OpenClaw bridge
• PydanticAI native adapter
• SpringAI / HTTP companion service
• LangChain (CoreMemory, CoreMemoryRetriever)
• Neo4j shadow graph adapter (projection-only visualization/inspection)

Good starting points

• Canonical first-touch
  • examples/canonical_5min.py
  • examples/quickstart.py
• Recommended value proofs
  • examples/proof_carry_forward.py
  • eval/reviewer_quick_value_v2.py
• Recommended integration starts
  • examples/pydanticai_basic.py
  • docs/integrations/springai/quickstart.md
  • docs/integrations/langchain/quickstart.md
  • docs/integrations/neo4j/quickstart.md
• Compatibility
  • examples/store_compat_quickstart.py

---

How It Works

Core Memory separates retrieval from writes, connected through session-scoped bead storage. Each agent turn follows the same loop:

1. Inject — build a bounded context packet
2. Execute — run the agent turn
3. Extract — capture structured events as beads
4. Store — append to durable session/event surfaces
5. Compact — preserve important causal memory, compress the rest
6. Recall — retrieve causal chains when the agent needs them

---

Core Concepts

Beads

A bead is a structured memory event: decision, lesson, outcome, evidence, context, or another typed unit of recall.

Associations

Associations are explicit links between beads and remain queryable even as memory compacts.

Retrieval Pipeline

Canonical retrieval surfaces:

• search (anchor retrieval)
• trace (causal traversal)
• execute (single orchestration entrypoint)

Semantic mode behavior:

• CORE_MEMORY_CANONICAL_SEMANTIC_MODE=required (default) fails closed for query-based anchor lookup when semantic backend is unavailable.
• CORE_MEMORY_CANONICAL_SEMANTIC_MODE=degraded_allowed allows explicit degraded lexical fallback with markers.

Semantic backend deployment guidance:

• faiss-* local index is development/single-process oriented (single-writer).
• qdrant and pgvector are the recommended distributed-safe production backends.
• For multi-worker production deployments, avoid relying on local FAISS write paths.
• backend selection is explicit via CORE_MEMORY_VECTOR_BACKEND (local-faiss|qdrant|pgvector|chromadb).

See docs/semantic_backend_modes.md for backend mode details.

Hydration is explicit post-selection source recovery (turn/tools/adjacent), not a general retrieval mode.

Deep recall exists as a separate capability and is not the same thing as canonical hydration.

Retrieval is deterministic from indexed state.

---

Repo Map

core_memory/
├── persistence/
├── schema/
├── retrieval/
├── graph/
├── write_pipeline/
├── runtime/
├── association/
├── integrations/
├── policy/
└── cli.py

Other useful folders:

• examples/ runnable examples
• tests/ behavioral and regression coverage
• docs/ architecture, integration guides, and contracts
• plugins/ OpenClaw bridge assets
• demo/ live demo app and assets

---

Contributing

git clone https://github.com/JohnnyFiv3r/Core-Memory.git
cd Core-Memory
python3 -m venv .venv
source .venv/bin/activate
pip install -U pip
pip install -e ".[dev]"
core-memory --help
python3 -c "import core_memory; print('core_memory import ok')"
pytest

Useful docs:

• CONTRIBUTING.md
• docs/public_surface.md
• docs/index.md

---

Inspiration

Inspired in part by Steve Yegge’s writing on beads and memory systems: https://github.com/steveyegge/beads

---

Maintainers

Core Memory is maintained by:

• John Inniger (@JohnnyFiv3r)
• Chris Dedow (@chrisdedow)

For bugs and feature requests, please open an issue. For anything else related to the project, feel free to reach out to the maintainers directly.

---

Apache-2.0 License · Code of Conduct · Changelog