omni-agent-memory 0.1.1

OmniMemory — a namespaced, structured memory service for Claude Code and other agents

OmniMemory

A structured, namespaced memory service for Claude Code and other agents. Agents push raw conversation turns to /ingest and pull context-scoped memory from /retrieve. The work that builds memory (extraction, verification, cascade, reconstruction) runs in the background on a cheap construction model — off the answer model's critical path — while memory is stored as several decoupled, single-purpose indices plus a dependency-rule engine, not one consolidated note.

On the MeME benchmark (six memory tasks × two domains, 100 episodes, opus-judged), OmniMemory scores 84.9% vs. 73.8% for Claude Code's built-in consolidate-over-notes memory (AutoDream) — +11 points, leading on five of six tasks, with the largest gaps on Deletion (+30), Tracking (+17), Absence (+13), and Cascade. See docs/paper/OmniMemory_vs_AutoDream.md.

   Claude Code ──hooks──▶ omni CLI ─┐
               ──MCP────▶ omni mcp ─┤ HTTP :11435
                                    ▼
                            OmniMemory (FastAPI)
            OmniEngine ──▶ construction model (local gemma · your Claude
                    │        Code Sonnet · or deepseek-chat) — background
                    ▼
            ~/.omni/<client_id>/<namespace>/
              state · history · deletions · rules · pages · raw

Install

pip install omni-agent-memory      # distribution name; the import/CLI is `omni`

Quickstart — replace AutoDream in Claude Code

# 1) run the local memory sidecar (FastAPI on 127.0.0.1:11435)
omni serve

# 2) pick a construction model (the work kept OFF your answer-model latency):
#    a) your existing Claude Code subscription's Sonnet — no extra API key, no metered cost:
export OMNI_EXTRACT_MODEL=claude-code/sonnet OMNI_VERIFY_MODEL=claude-code/sonnet
#    b) free + fully local (Ollama):   OMNI_EXTRACT_MODEL=gemma4-ctx32k
#    c) cheap cloud:                    OMNI_EXTRACT_MODEL=deepseek-chat   (needs DEEPSEEK_API_KEY)

# 3) wire a repo with one command (idempotent): merges hooks into .claude/settings.json
#    and writes .mcp.json
omni install-hooks --project .

That installs the standard Claude Code wiring:

// .claude/settings.json
{ "hooks": {
    "SessionStart":     [{ "hooks": [{ "type": "command", "command": "omni retrieve --session-start" }]}],
    "UserPromptSubmit": [{ "hooks": [{ "type": "command", "command": "omni ingest" }]}],
    "Stop":             [{ "hooks": [{ "type": "command", "command": "omni ingest" }]}]
}}
// .mcp.json
{ "mcpServers": { "omni": { "command": "omni", "args": ["mcp"] } } }

Capture is deterministic (hooks push every turn to /ingest, which returns immediately; construction runs in the background). Recall is a SessionStart seed plus the MCP tools memory_search(query) / memory_note(text). Memory is per-project by default (namespace = project dir, client = claude-code).

A hosted OmniMemory Online Service (zero local setup; point the same hooks at a managed endpoint) is on the roadmap.

Why structured memory

A long-horizon agent's memory must do more than retrieve similar text — MeME formalizes six tasks, each a distinct failure mode, and OmniMemory gives each a purpose-built store:

Task	Needs	OmniMemory store
ER Exact Recall	verbatim fact	raw/ archive + state.json
Agg Aggregation	combine scattered facts	list entities + pages
Tr Tracking	full revision history	history.jsonl + chains.json
Del Deletion	recognize removals, withhold old value	deletions.json tombstones
Cas Cascade	propagate a stated dependency	rules.json + cascade-to-fixpoint
Abs Absence	admit uncertainty when no replacement	rules with null → uncertain

The dependency-rule engine is what most distinguishes it: when the user states "if my X changes, my Y becomes Z" (or "my Y depends on my X"), OmniMemory records a rule and, when the trigger later changes, deduces the new value (Cascade) or flags uncertainty (Absence) — answers that a consolidated note cannot preserve. Strip the rule engine out and Cascade collapses from 88% to 2%.

Code map

File	Role
omni/engine.py	OmniEngine: ingest → background EXTRACT/RELATE → debounced VERIFY → CASCADE → RECONSTRUCT → retrieve
omni/storage.py	Per-namespace on-disk stores (raw / state / history / deletions / rules / pages / vectors)
omni/server.py	FastAPI HTTP service + /ui inspector
omni/cli.py	omni CLI (hook client + install-hooks + serve/mcp)
omni/mcp_server.py	MCP stdio server — memory_search / memory_note
omni/llm.py, omni/prompts.py, omni/config.py	model routing, memory-op prompts, env config

HTTP API (quick check)

curl -s localhost:11435/health
curl -s -X POST localhost:11435/ingest  -H 'Content-Type: application/json' \
  -d '{"client_id":"alice","namespace":"proj","turns":[{"role":"user","content":"My medication is Quelmithin."}],"timestamp":"2023/03/17"}'
curl -s -X POST localhost:11435/retrieve -H 'Content-Type: application/json' \
  -d '{"client_id":"alice","namespace":"proj","query":"medication","mode":"search"}'

client_id is required and partitions storage as ~/.omni/<client_id>/<namespace>/. A built-in memory inspector is at http://127.0.0.1:11435/ — an action log of every EXTRACT/RELATE/VERIFY call (request, response, applied writes) plus the current snapshot.

Configuration (env vars)

Var	Default	Meaning
OMNI_STORAGE_ROOT	~/.omni	Storage root (<client_id>/<namespace>/)
OMNI_CLIENT_ID	claude-code	Default client id for the CLI/MCP clients
OMNI_HOST / OMNI_PORT	127.0.0.1 / 11435	HTTP bind
OMNI_EXTRACT_MODEL / OMNI_VERIFY_MODEL	gemma4-ctx32k	Construction tier — gemma4-ctx32k (local), claude-code/sonnet, or deepseek-chat
OMNI_ANSWER_MODEL	claude-code	Optional engine-side answer ensemble
OMNI_VECTOR_ENABLED	1	Vector sub-paths (needs nomic-embed-text via Ollama)
OMNI_VERIFY_DEBOUNCE_SECONDS	20	Idle window before background VERIFY

For a fully-local construction tier via Ollama (note: the OpenAI /v1 path runs Ollama at a baked-in context, so use a large-context variant):

ollama pull gemma4:e4b
printf 'FROM gemma4:e4b\nPARAMETER num_ctx 32768\n' > /tmp/Modelfile.ctx32k
ollama create gemma4-ctx32k -f /tmp/Modelfile.ctx32k
ollama pull nomic-embed-text          # embeddings, if OMNI_VECTOR_ENABLED=1

Documentation

• docs/paper/OmniMemory_vs_AutoDream.md — design + benefits vs. Claude Code's AutoDream, with the MeME metrics
• docs/paper/OmniMemory.md — full design paper
• docs/OmniMemory_design.md, docs/integration_design.md — design + agent integration

License

Apache-2.0.