API reference

The MemoryCore public API — constructor, ingestion, recall, lifecycle, versioned governance, AgentJournal compilation, MCP tools, CLI, and environment variables.

This document describes the stable public API for CoreMem 0.16.x, verified against the source in coremem/.

MemoryCore

from coremem import MemoryCore

core = MemoryCore(
    path="./memory",
    llm_provider=None,
    agent_journal_model="openai:gpt-4o-mini",
    fact_augment=False,
    versioned=True,
    author=None,
)

path str REQUIRED

Memory storage directory. Created if missing.

llm_provider object OPTIONAL default: None

Provider for AgentJournal compilation. Usually leave None and set COREMEM_LLM_MODEL instead.

agent_journal_model str OPTIONAL default: openai:gpt-4o-mini

Compilation model string (e.g. ollama:llama3.2).

fact_augment bool OPTIONAL default: False

Fact-augmented key expansion — falsified on LongMemEval S (neutral); leave off.

versioned bool OPTIONAL default: True

Tamper-evident hash chain over messages and journal records (new stores only). Enables the governance API.

author str OPTIONAL default: None

Optional author recorded on every versioned-history event.

MemoryCore supports the context manager protocol (with MemoryCore(path=...) as core) — closing releases the store and models.

get_core (factory)

from coremem import get_core

core = get_core()                       # path arg > COREMEM_PATH env > ~/.coremem/hybrid
core = get_core("./memory")

Resolution: path argument → COREMEM_PATH env → ~/.coremem/hybrid. Reads COREMEM_LLM_MODEL for the provider.

Ingestion

core.ingest(role, content, session_id=None, user_id="", agent_id="",
            ts=None, metadata=None, embedding=None, turn_id=None) -> str
core.ingest_turn(messages: list[dict], session_id=None) -> str
core.ingest_many(messages: list[dict]) -> list[str]

ingest / ingest_turn return the turn_id (needed for compile).
ingest_many / store return message ids.
ingest raises ValueError on empty content (a silent no-op would hide storage failures); ingest_turn/ingest_many skip empty messages.
Optional per-message: user_id, agent_id, ts, metadata, pre-computed embedding.

recall

core.recall(query: str, *, ...) -> list[SearchResult] | list[SessionBundle]

strategy str OPTIONAL default: episodic

episodic (zero-LLM, full pipeline), direct (zero-LLM), expanded (1 LLM call), fusion (zero-LLM, RRF of direct + episodic).

limit int OPTIONAL default: 5

Maximum results.

bundles bool OPTIONAL default: False

Return SessionBundle objects (4k-char budget, evidence-first ordering) instead of flat results.

session_cap int OPTIONAL default: 1

Episodic only: allow up to N messages per session (+0.124 message recall at −0.058 session recall — opt-in tradeoff).

filters dict OPTIONAL

Keyword-only filters applied to all strategies: role, session_id, user_id, agent_id, ts_after, ts_before, metadata.

Memory lifecycle

core.fetch(role=None, session_id=None, user_id=None, agent_id=None,
           ts_after=None, ts_before=None, metadata=None, limit=1000, offset=0)
core.fetch_all()
core.store([Memory(id="m1", content="...")])    # returns message ids
core.count()
core.delete(session_id="conv_001")
core.list_sessions()         # [{session_id, messages, last_ts}] most recent first
core.delete_messages([mid])  # ids appear in recall output
core.stats()                 # {messages, sessions, users, last_ts, journal_pending}
core.clear()

with MemoryCore(path="./memory") as core:   # context manager closes resources
    ...

Versioned governance (versioned stores only)

core.checkpoint_memory(label: str)
core.rollback_memory(label=None, seq=None)
core.memory_log(limit=100)
core.memory_history(message_id)      # provenance timeline
core.memory_diff(from_seq, to_seq)
core.as_of_memory(seq)
core.verify_memory_chain()           # -> {"valid": ...}

MCP equivalents: memory_history, memory_rollback (requires confirm=true), memory_verify — agents and operators can self-audit.

AgentJournal

await core.compile_turn(turn_id, timestamp=None, title=None, *, force=False)
await core.compile_latest_turn(session_id, ...)
await core.compile_uncompiled_turns(...)
await core.dream()
core.rebuild_index()

Compilation is idempotent per source: re-compiling an unchanged turn returns None; a changed turn raises unless force=True (appends a new section). dream() appends analysis + promoted facts to DREAMS.md; MEMORY.md is compiler-owned.

MCP server

coremem mcp        # stdio server (the default command)

Tool	Notes
`recall`	Full filter surface + `session_cap`; output includes message ids
`ingest`	Stores a message
`delete`	By message ids
`fetch_session` / `list_sessions`	Session inspection
`stats`	Memory statistics
`compile` / `rebuild_index`	Journal operations
`memory_history` / `memory_rollback` / `memory_verify`	Governance (rollback requires `confirm=true`)

CLI

coremem recall "model kits" --strategy direct
coremem ingest user "I built a Spitfire model kit" --session-id conv_001
coremem compile <turn_id>
coremem rebuild
coremem sessions
coremem stats
coremem delete <message_id...>
coremem mcp      # default command
coremem hook     # hook handler (reads JSON from stdin)

Environment variables

Variable	Purpose
`COREMEM_PATH`	Memory storage path (default `~/.coremem/hybrid`)
`COREMEM_LLM_MODEL`	LLM model for journal compilation (e.g. `openai:gpt-4o-mini`, `ollama:llama3.2`)
`COREMEM_CROSS_ENCODER_MODEL`	Cross-encoder override (e.g. `ms-marco-MiniLM-L-12-v2`)
`DISABLE_CROSS_ENCODER`	`1` skips cross-encoder reranking
`OPENAI_API_KEY` / `ANTHROPIC_API_KEY` / `GEMINI_API_KEY` / `OLLAMA_API_KEY`	Provider keys for LLM-backed features

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