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

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)

• Canonical surfaces: process_turn_finalized(turns=[...]) / 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

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(turns=[...])
  • 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.

• Required
  • base install: pip install core-memory
  • canonical write boundary: process_turn_finalized(turns=[...])
  • 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/

• 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

Watch the Core Memory live demo on YouTube

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.

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.

pip install core-memory

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 .

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]"

Use capture for observed conversation writes and recall for single-query reads. capture is the quick-start helper for the canonical process_turn_finalized(turns=[...]) boundary; recall currently delegates to memory_execute(...). See docs/concepts/turn_schema.md for the multi-speaker turn schema and migration notes.

from core_memory import capture, recall

root = "./memory"

capture(
    root=root,
    session_id="quickstart",
    turn_id="t1",
    user="Why did we choose Postgres?",
    assistant="Decision: choose Postgres because JSONB lowers integration risk.",
)

out = recall("why did we choose Postgres?", root=root)
print(out.get("ok"), len(out.get("results") or []))

remember(...) is intentionally not part of this surface yet; that future verb is reserved for declarative user-authored memory writes (tracked separately in TODO #21 / future PRD work).

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",
    turns=[
        {"speaker": "user", "role": "user", "content": "What should we do about Redis timeouts?"},
        {"speaker": "assistant", "role": "assistant", "content": "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",
    turns=[
        {"speaker": "user", "role": "user", "content": "What should we do about Redis timeouts?"},
        {"speaker": "assistant", "role": "assistant", "content": "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

from core_memory import process_turn_finalized, memory_execute

root = "./memory"

process_turn_finalized(
 root=root,
 session_id="s1",
 turn_id="t1",
 turns=[
  {"speaker": "user", "role": "user", "content": "Why did Redis fail?"},
  {"speaker": "assistant", "role": "assistant", "content": "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 []))

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}'

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

See:

• examples/store_compat_quickstart.py

For JVM, JS/TS-adjacent, or service-oriented architectures, run Core Memory as a companion HTTP 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"

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
 }'

Send finalized assistant turns to:

• POST /v1/memory/turn-finalized

Minimum useful fields:

• session_id
• turn_id
• turns — list of {speaker, role, content} objects

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)

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

from core_memory import process_turn_finalized

Adapter/helper ingress remains available for bridge code:

from core_memory.integrations.api import emit_turn_finalized

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

• 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

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

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

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

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.

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

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

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

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