Quick Start

This guide walks through the core Cerememory workflow: start one long-lived server for your data directory, point every MCP client (or any HTTP/gRPC client) at it, and store, recall, and forget a memory.

Start the Shared Server

Cerememory's only supported operating mode is one long-lived server process per data directory. The server owns the embedded redb and Tantivy stores exclusively. Every MCP client, CLI invocation, and HTTP caller then talks to that shared server.

target/release/cerememory serve --data-dir ~/.cerememory/data

Example startup output:

Cerememory v0.2.5
HTTP  listening on 127.0.0.1:8420

Default behavior:

• HTTP bound to 127.0.0.1:8420
• Persistent redb stores for episodic, semantic, procedural, emotional, and raw journal memory
• In-memory working memory (never persisted)
• Background decay tick (decay.background_interval_secs = 3600)
• Background dream processing (dream.background_interval_secs = 86400)
• /health and /readiness enabled
• /metrics disabled until http.metrics_enabled = true

Connect an MCP Client

cerememory mcp is a thin stdio proxy that speaks MCP to the client and CMP/HTTP to the shared server. --server-url is required.

target/release/cerememory mcp --server-url http://127.0.0.1:8420

Point every MCP-compatible client at that same server. The same binary works with Claude Code, OpenAI Codex CLI, Cursor, Cline, Windsurf, Zed, Continue, and any other client that speaks MCP.

See MCP & Agent Setup for per-client configuration snippets.

Store a Memory

store(
  content="The user prefers dark mode and uses vim keybindings.",
  store="semantic",
  meta_json='{"intent":"capture stable user preference","confidence":0.9,"tags":["preferences","ui"]}'
)

Recall Memories

recall(query="What are the user's preferences?", limit=5, mode="human")

Preserve Raw Journal Entries

Raw journal records keep the verbatim source material that dream processing can later summarize into curated episodic and semantic memory.

store_raw(
  text="The user said they prefer Neovim and keep tmux open all day.",
  session_id="sess_001",
  source="conversation",
  speaker="user"
)
 
dream_tick(session_id="sess_001")

Forget a Memory

forget(record_ids=["01916e3a-1234-7000-8000-000000000001"], confirm=true)

Check System State

curl http://127.0.0.1:8420/readiness
curl http://127.0.0.1:8420/v1/introspect/stats

/readiness is unauthenticated and intended for probes. /v1/introspect/stats is the full CMP stats endpoint.

Next Steps