Memora

Persistent, semantic memory for AI coding agents — local-first, MCP-native.

A local, persistent, semantically-aware knowledge graph for Claude Code (and any MCP-compatible AI coding agent). Auto-loads in every session in every project. Zero per-project setup, zero network calls at runtime, ~85–95% lower per-session context cost than naïve "load it all" memory.

git clone https://github.com/VnemAIDev/memora.git
cd memora
./install.sh --bootstrap

That's the full install. Open Claude Code in any directory; memory auto-loads. See QUICKSTART.md for prerequisites and troubleshooting.

At a glance

• Install root: ~/.claude-memory/

• Database: ~/.claude-memory/graph.db (SQLite, WAL mode)

• Total disk: ~320 MB (venv 227 MB + ONNX model 90 MB + DB ~2 MB)

• Registered scope: user-level MCP server (claude mcp list → memory)

• Global protocol: ~/.claude/CLAUDE.md

• Runtime network calls: zero (model is downloaded once at install time)

Related MCP server: GraphHub

Quick start (for a fresh reader)

# Verify the server is registered and reachable
claude mcp list

# Check semantic coverage
~/.claude-memory/.venv/bin/python -c "
import sys; sys.path.insert(0,'$HOME/.claude-memory')
import embeddings; print(embeddings.status())"

# Inspect the DB directly
sqlite3 ~/.claude-memory/graph.db \
  "SELECT project, COUNT(*) FROM entities GROUP BY project;"

# Periodic maintenance (dedupe observations)
~/.claude-memory/.venv/bin/python ~/.claude-memory/compact.py --aggressive --semantic 0.92

File inventory

Build timeline — 4 phases

Phase 1 — Base infrastructure

Minimal MCP server matching the original spec.

• Schema: 4 tables (entities, observations, relations, tags) + 7 indexes, WAL mode, foreign keys

• Tools (8): recall_context, create_entity, add_observation, create_relation, search, get_entity, list_projects, forget

• Project auto-detection: CWD basename → project name ($HOME and / → "global")

• Registration: claude mcp add --scope user memory -- ~/.claude-memory/run.sh

Phase 2 — First token-optimization pass (7 wins)

Targeted the biggest pain point: recall_context() returning ~8 KB of mostly-redundant JSON.

Phase 3 — External research pass (Caveman / RTK / Supermemory)

Researched 3 token-optimization projects in parallel; ported the high-ROI ideas.

Phase 4 — Semantic layer (Supermemory's biggest idea)

Hybrid lexical + semantic search, all local.

The complete tool surface — 12 tools

recall_context       create_entity         add_observation
create_relation      search                get_entity
list_projects        forget                set_summary
summarize_project    embedding_status      flag_for_summary

Measured token savings (real project data)

Numbers from the actual smoke tests during the build, on the demo project project with 5 entities and 20 observations:

At a glance: characters ÷ 4 ≈ tokens. Old startup recall cost ~2,100 tokens; the new ritual (summarize_project → selective get_entity) costs ~100-400 tokens depending on what's relevant. 5-20× reduction per session start.

Operational benefits — behavioral wins that compound

Continuous wins

1. No per-project setup cost. Every new project already has full memory. Zero friction.

2. Cross-session continuity. State that previously lived in fragile MEMORY.md files now lives in a queryable DB.

3. Type-aware retrieval. Asking "what conventions apply here?" returns conventions first.

4. Semantic recall. Don't have to remember exact words. "The thing about animation" finds entities tagged #hero even if "animation" isn't in any observation.

5. Cheap upkeep. compact.py --aggressive --semantic 0.92 weekly keeps the DB lean.

6. Privacy. All-local. Model cached. No telemetry. No data leaves the machine.

Cost accounting

Memory Protocol (what Claude is told to do, from ~/.claude/CLAUDE.md)

Session start ritual

1. summarize_project() — one line per entity, ~95% cheaper than full recall

2. flag_for_summary() — for any entity with >5 observations and no summary, call set_summary(name, "<gist>") to short-circuit raw observations on future recalls

3. recall_context() for the active subset, or get_entity(name) for specific entities

What to write

• decision + rationale (entity_type="decision")

• file purpose / important state (entity_type="file")

• pending task / blocker (entity_type="todo")

• user preference / convention (entity_type="convention")

• external service / API / dependency (entity_type="service")

• person / team member (entity_type="person")

Active-voice relations only: uses, depends_on, blocks, replaces, owns, reports_to, calls, extends.

Keep tokens low

• Default lean shape; pass verbose=True only when needed

• Read omitted_names from truncated responses; use get_entity() for specifics

• @dup:<name> in observations means deduplicated, not missing

• Tag stale entities archived for auto-exclusion

• Use since_days=N for recent-only context

• Use search(query, project="*") for cross-project lookups

• Run compact.py --aggressive --semantic 0.92 periodically

Safety

Never store secrets, API keys, passwords, or PII. Reference them by name only (e.g., "uses Stripe API key stored in 1Password as STRIPE_PROD").

Maintenance commands

# Check semantic search status
~/.claude-memory/.venv/bin/python -c "
import sys; sys.path.insert(0,'$HOME/.claude-memory')
import embeddings; print(embeddings.status())"

# Re-embed every observation (after model swap)
~/.claude-memory/.venv/bin/python ~/.claude-memory/bootstrap_embeddings.py --rebuild

# Dry-run dedupe (no writes)
~/.claude-memory/.venv/bin/python ~/.claude-memory/compact.py --dry-run --aggressive --semantic 0.92

# Real dedupe + VACUUM
~/.claude-memory/.venv/bin/python ~/.claude-memory/compact.py --aggressive --semantic 0.92

# Health check
claude mcp list

# Activity log
grep "memory server starting" ~/.claude-memory/server.log

# Errors
grep -E "ERROR|failed|Traceback" ~/.claude-memory/server.log

# Direct DB stats
sqlite3 ~/.claude-memory/graph.db "
  SELECT project, COUNT(*) AS entities FROM entities GROUP BY project;
  SELECT 'total observations: ' || COUNT(*) FROM observations;
  SELECT 'embedded observations: ' || COUNT(*) FROM observations WHERE embedding IS NOT NULL;
  SELECT 'total relations: ' || COUNT(*) FROM relations;
"

What this means in practice

A typical session before this work would either (a) ignore memory and re-ask questions Claude should know the answer to, or (b) load 2-8 KB of memory tokens at session start whether useful or not, possibly missing concept-level matches when searching.

Now: Claude opens the session, calls summarize_project() for ~100 tokens, scans for what's relevant, calls flag_for_summary() to spot bloated entities, then fetches detail only where it matters. Median session-start memory cost: 300-800 tokens, down from 2,000+ tokens. Over 100 sessions a month that's 120K+ tokens saved on memory loading alone — and that ignores the bigger win of finding context lexical search would have missed entirely.