Quickstart

Install CoreMem, ingest a conversation, and run your first zero-LLM recall — plus session bundles, filters, and Claude Code wiring in minutes.

Install

Install the package

pip install coremem

Optional extras:

pip install "coremem[mcp]"    # MCP server
pip install "coremem[all]"    # all extras

Ingest a conversation

from coremem import MemoryCore

core = MemoryCore(path="./memory")

# Simple ingestion
core.ingest("user", "I built a Spitfire model kit", session_id="conv_001")

# Batch ingestion (one turn = one turn_id)
core.ingest_turn([
    {"role": "user", "content": "What's the weather today?"},
    {"role": "assistant", "content": "Sunny with a high of 72°F"},
], session_id="conv_001")

Recall — zero LLM calls

results = core.recall("How many model kits?", limit=10)
results = core.recall("What did I build recently?", strategy="direct")

# Filter params
results = core.recall("coffee", role="user", session_id="conv_001", ts_after="2024-01-01")

Session bundles

bundles=True returns the surrounding context around each hit — 4k-char total budget, evidence-first ordering (retrieved anchors lead), the validated default:

bundles = core.recall("model kits", bundles=True)
for b in bundles:
    print(f"## Session {b.session_id} (complete={b.complete})")
    for m in b.messages:
        print(f"  [{m.role}] {m.content}")

Session-cap selection

session_cap=2 allows up to 2 messages per session instead of the one-per-session MMR cap — recovers answers in a second message of an already-found session (+0.124 message recall, at −0.058 session recall; a documented tradeoff).

Compile into the AgentJournal

ingest/ingest_turn return a turn_id — feed it to the compiler:

await core.compile_turn(turn_id=tid)                 # daily/YYYY-MM-DD.md
await core.compile_latest_turn(session_id="conv_001")
await core.dream()                                   # consolidation into DREAMS.md
core.rebuild_index()                                 # weekly/monthly navigation

Wire it into your coding agent

coremem recall "model kits" --strategy direct
coremem ingest user "I built a Spitfire model kit" --session-id conv_001
coremem mcp   # MCP stdio server (also the default command)

MCP server — 8 tools: recall (with filters + session_cap), ingest, delete, fetch_session, list_sessions, stats, compile, rebuild_index
Hooks — Claude Code and Codex: UserPromptSubmit (capture + retrieval injection), Stop (capture)
Integration configs ship in integrations/ for Claude Code, Codex, and OpenCode

First-run model downloads

ChromaDB downloads a bundled MiniLM embedding (~80MB) on first init; the cross-encoder downloads ms-marco-MiniLM-L-6-v2 (~500MB) on the first episodic recall. Both cache locally — run one recall at startup to pre-load models predictably.

Continue to Core concepts for the strategies and heuristics, or the API reference for every method.

Source of truth for this page: CoreMem · open-assistants-lab/CoreMem