Ogham Mcp

Ogham(pronounced "OH-um") -- persistent, searchable shared memory for AI coding agents. Works across clients.

AI coding agents forget everything between sessions. Switch from Claude Code to Cursor to Kiro to OpenCode and the context is gone -- decisions, gotchas, the shape of your codebase -- so you repeat yourself, re-explain, and re-debug the same issues.

Ogham gives your agents one shared memory that persists across sessions and clients. It is aretrieval engine: it stores what matters and finds it again, and your LLM reads the results.

The retrieval isstructured-- hybrid search plus a typed-edge graph, not just vector similarity. That is what lets it answer questions whose answer is apath between two facts, the case where plain vector RAG falls down.

ogham initruns a setup wizard: it connects your database, picks an embedding provider, migrates the schema, and writes the MCP client config (Claude Code, Cursor, VS Code, and others). For Claude Code it runsclaude mcp addfor you; for other clients it prints the snippet to copy.

You need a database first-- a freeSupabaseproject or aNeondatabase. On Neon or self-hosted Postgres, install the postgres extra so the driver is available:

uvx --from 'ogham-mcp[postgres]' ogham init

Then tell your agent to remember something and ask about it later -- from the same client or a different one. They share the database, so the memory follows you.

If you'd rather configure things yourself instead of using the wizard:

# Supabase export SUPABASE_URL=https://your-project.supabase.co export SUPABASE_KEY=your-service-role-key export EMBEDDING_PROVIDER=openai # or ollama, mistral, voyage export OPENAI_API_KEY=sk-... # for your chosen provider # Or Postgres (Neon, self-hosted) export DATABASE_BACKEND=postgres export DATABASE_URL=postgresql://user:pass@host/db export EMBEDDING_PROVIDER=openai export OPENAI_API_KEY=sk-...

Run the schema migration (sql/schema.sqlfor Supabase,sql/schema_postgres.sqlfor Neon/self-hosted), then add the MCP server to your client.

OpenCode-- add to~/.config/opencode/opencode.json:

{ "mcp": { "ogham": { "type": "local", "command": ["uvx", "ogham-mcp"], "environment": { "SUPABASE_URL": "https://your-project.supabase.co", "SUPABASE_KEY": "{env:SUPABASE_KEY}", "EMBEDDING_PROVIDER": "openai", "OPENAI_API_KEY": "{env:OPENAI_API_KEY}" } } } }

docker run --rm \ -e SUPABASE_URL=https://your-project.supabase.co \ -e SUPABASE_KEY=your-key \ -e EMBEDDING_PROVIDER=openai \ -e OPENAI_API_KEY=sk-... \ ghcr.io/ogham-mcp/ogham-mcp

git clone https://github.com/ogham-mcp/ogham-mcp.git cd ogham-mcp uv sync uv run ogham --help

By default, Ogham runs in stdio mode -- each MCP client spawns its own server process. To let several agents share one server, run it over HTTP:

ogham serve --transport streamable-http --port 8742

The server runs as a persistent background process. All clients connect to the same instance -- one database pool, one embedding cache, shared memory.

{ "mcpServers": { "ogham": { "url": "http://127.0.0.1:8742/mcp" } } }

Health check athttp://127.0.0.1:8742/health(cached, sub-10ms). Configure via env vars (OGHAM_TRANSPORT=streamable-http,OGHAM_HOST,OGHAM_PORT) or CLI flags.httpis accepted as an alias forstreamable-http.

In Docker, bind to all interfaces.The default host is127.0.0.1, which inside a container means the container itself -- publishing the port will not reach it:

docker run -p 8742:8742 ghcr.io/ogham-mcp/ogham-mcp:latest \ serve --transport streamable-http --host 0.0.0.0 --port 8742

Ogham still accepts--transport sseand serves that endpoint at/sse. It works, and it stays for existing deployments, but new setups should use streamable-http.

The MCP specification now defines two standard transports, stdio and Streamable HTTP, and treats HTTP+SSE as deprecated. The difference that matters is what happens when a session is lost. Streamable HTTP assigns anMcp-Session-Idand defines the way back: the server answers a dead session with HTTP 404, and the client starts a fresh one. SSE defines no recovery at all, so a session that loses its initialized state rejects every later request with-32602, and the client cannot tell a lifecycle problem from a bad argument. One dropped connection can leave an agent failing every call until someone restarts it.

- ogham-- the CLI. Use this forogham init,ogham health,ogham search, and other commands you run yourself. Runningoghamwith no arguments starts the MCP server.
- ogham-serve-- starts the MCP server directly. This is what MCP clients should call. When you runuvx ogham-mcp, it invokesogham-serve.

Ogham is a retrieval engine -- it finds the memories, your LLM reads them. The headline numbers, and they measure different things:

- Retrieval:97.2% R@10 on LongMemEvalwithone Postgres query(pgvector + tsvector CCF hybrid search). Thepaperbaseline is 78.4%. Other systems that report similar R@10 typically stack cross-encoder reranking, NLI verification, and knowledge-graph enrichment.
- End-to-end QA:85.8% on theAMB harness(500 questions, April 2026, strict substring judge, GPT-5-mini reader; R@10 99.5%), and0.554 nugget onBEAM100K(paper baseline 0.358; seven of nine categories beat the paper).

QA accuracy tests whether the full system (retrieval + LLM) produces the correct answer. R@10 tests whether retrieval alone found the right memories. Full tables, methodology, and the competitor comparison live atogham-mcp.dev/features; the write-ups explain why the AMB and internal numbers differ (LongMemEval,BEAM).

85.8% QA accuracy on theAMB benchmark harness(500 questions, April 2026) -- 429/500 questions answered correctly using GPT-5-mini with reasoning, evaluated by Gemini 2.5 Flash Lite as a strict judge. Retrieval R@10: 99.5%. AMB is the standardised evaluation harness built by theVectorizeteam (creators of Hindsight). Thanks to Nicolo and the Vectorize team for making the harness open.

Previously: 91.8% on our internal LongMemEval benchmark pipeline (gpt-5.4-mini reader, rubric judge). The AMB number is lower because AMB uses a stricter substring-matching judge -- see thefull write-upfor methodology differences.

0.554 nugget score onBEAM100K(400 questions across 10 memory abilities, ICLR 2026), using the paper's exact judge prompt from Appendix G. The published baseline is 0.358 (Llama-4-Maverick + LIGHT). Retrieval R@10: 0.737. Seven of nine categories beat the paper.Full write-up.

Other retrieval systems that report similar R@10 numbers typically use cross-encoder reranking, NLI verification, knowledge graph enrichment, and LLM-as-a-judge pipelines. Ogham reaches 97.2% with one Postgres query. OptionalFlashRank rerankingis available for self-hosters who want extra ranking precision.

AI Client (Claude Code, Cursor, Kiro, OpenCode, ...) | | stdio or SSE (MCP protocol) | Ogham MCP Server | | HTTPS (Supabase REST API) or direct connection (Postgres) | PostgreSQL + pgvector

- Memory operations-- store memories, decisions, preferences, facts, and events; update, reinforce, and contradict.
- Hybrid search-- semantic + full-text (RRF), tag filters, multi-profile search, read-time fact extraction.
- Typed-edge graph (v0.16)--store_triple/query_joinfor two-fact join queries against a controlled predicate vocabulary.docs
- Knowledge graph-- auto-linking, spreading-activation retrieval, and connection suggestions via shared entities.
- Wiki layer-- synthesize a tag's memories into a cached markdown page; walk the graph; lint health.
- Open Knowledge Format-- portable round-trip bundles (markdown + a self-contained graph viewer), OKF v0.1.
- Entity enrichment-- regex entity tags across 18 languages with no LLM in the write path; a timeline table; Lost-in-the-Middle reordering.
- Memory lifecycle-- FRESH / STABLE / EDITING stages, ACT-R importance, Hebbian decay, and automatic condensing.
- Importers-- Claude Code auto-memory, Claude.ai export, Linear issues, and JSON.
- Ingestion adapters (v0.17)-- capture into memory from an Obsidian/markdown vault (ingest-obsidian), Telegram (ingest-telegram), and Slack (ingest-slack). Outbound-only, idempotent, and timer-friendly; all three share one server-side enrichment and dedup path.
- Lifecycle hooks-- recall context at session start, inscribe signal (not noise) after tool use; secrets masked before storage.
- Skills--ogham-research,ogham-recall,ogham-maintain.
- Self-hoster options-- ONNX local embeddings (BGE-M3), optional FlashRank reranking, five embedding providers.

Full reference for every tool, env var, and setup path is inReferencebelow.

- Hybrid search-- Reciprocal Rank Fusion (Cormack, Clarke & Butt, SIGIR 2009): dense vector similarity rank-fused with BM25-style keyword matching, no score normalisation.
- ACT-R importance + Hebbian decay-- recency, frequency, and surprise weighting (Anderson & Lebiere, 1998;Hebb, 1949). Unaccessed memories fade; frequently accessed ones potentiate and persist.
- Read-time fact extraction-- verbatim storage with query-aware extraction at retrieval, so the ground truth stays re-extractable with different questions later (Anthropic, arXiv:2510.05179). Supports local models via Ollama for full data sovereignty.
- Contradiction detection + supersession-- opposite-polarity memories are linked, not deleted; the edge records that the newer memory superseded the older one.
- Append-only audit trail-- every store, search, delete, and update logged to anaudit_logtable in the same Postgres instance, aligned with GDPR Article 15 andOTEL GenAI conventions.

Hybrid search-- Reciprocal Rank Fusion (Cormack, Clarke & Butt, SIGIR 2009) combining dense vector similarity (pgvector) with BM25-style keyword matching (PostgreSQL tsvector). Two independent retrieval systems, rank-fused without score normalisation.

Entity overlap boost-- memories sharing named entities with the query receive a bounded relevance boost (up to 1.4x), inspired by entity-linking literature (Kolitsas et al., CoNLL 2018). Entity extraction covers 18 languages via YAML-based word lists with no LLM in the write path.

Matryoshka embeddings-- flexible dimensionality via Matryoshka Representation Learning (Kusupati et al., NeurIPS 2022). Embedding providers (OpenAI, Voyage, Gemini, Ollama) produce native-dimension vectors truncated to 512d, enabling provider-portable storage without re-embedding.

Temporal diversity re-ranking-- density-gated soft penalty preventing semantic clustering on a single time period, extending Maximal Marginal Relevance principles (Carbonell & Goldstein, SIGIR 1998). Only activates when the top-k results are temporally concentrated, leaving well-distributed results untouched.

ACT-R importance scoring-- cognitive-architecture-inspired memory weighting based on recency, access frequency, and surprise (Anderson & Lebiere, 1998). Frequently accessed memories stay sharp, rarely accessed ones fade, disputed ones drop in ranking without deletion.

Hebbian decay and potentiation-- memories that are not accessed lose importance over time (5% per 30-day idle period). Memories accessed 10+ times become "potentiated" with a slower decay rate (1% per 30 days), simulating long-term potentiation. Based on Hebb's learning rule (Hebb, 1949) and computational models of synaptic plasticity (Bi & Poo, 2001). Importance serves as a multiplier in the relevance formula -- decayed memories sink in rankings but remain retrievable (floor at 0.05). Original importance is preserved in metadata for recovery. Run as a batch job viaogham decayor pg_cron.

Memory lifecycle (v0.11.0): FRESH / STABLE / EDITING.Every memory now has an explicit stage tracked in a dedicatedmemory_lifecycletable. New memories land atfresh. The session-start hook sweeps aged fresh memories tostablewhen they clear an importance-or-surprise gate and have dwelled long enough. Retrieval opens a 30-minuteeditingwindow on the returned memories so follow-upupdate_memorycalls refine recent thoughts in place; windows auto-close on the next sweep. Memories retrieved together also strengthen their pairwise graph edges (eta=0.01 per co-retrieval, capped at 1.0). The design draws on three lines of prior art: Hebbian co-activation (Hebb, 1949), the hybrid exponential-then-power-law forgetting curve characterised byWixted (2004)building onEbbinghaus (1885), and the memory reconsolidation window from neuroscience (Nader, Schafe & LeDoux, 2000) for the editing-on-retrieval mechanic. Stage state lives in its own table so transitions do not touch the HNSW vector index.

Spreading activation-- when a search hits one memory, activation spreads along relationship edges to pull in connected memories that wouldn't have matched on their own. Integrated into cross-reference, ordering, and summary queries. Density-adaptive weighting means sparse graphs lean harder on graph signal, dense graphs rely more on retrieval score. Inspired by Collins & Loftus (1975) semantic network theory.

Read-time fact extraction-- query-aware extraction at retrieval time preserves verbatim storage for auditability, contrasting with write-time compression approaches. Verbatim storage ensures the ground truth is always available for re-extraction with different questions later -- a design choice informed by alignment considerations in persistent agent memory (Anthropic, arXiv:2510.05179). Supports local models via Ollama for full data sovereignty.

Append-only audit trails-- every store, search, delete, and update operation is logged to anaudit_logtable in the same Postgres instance. Designed for GDPR Article 15 subject access requests and cost governance. Fields align withOTEL GenAI Semantic Conventions. Query viaogham auditCLI. No extra infrastructure -- runs in the same database as memories.

ogham init # Interactive setup wizard ogham health # Check database + embedding provider ogham config # Show runtime configuration (secrets masked) ogham store "some fact" # Store a memory ogham search "query" # Search memories (hybrid: semantic + keyword) ogham search "q" --json # JSON output for scripting ogham search "q" --tags "a,b" # Filter by comma-separated tags ogham list # List recent memories ogham list --json # JSON output ogham delete <id> # Delete a memory by ID ogham use <profile> # Switch default profile ogham profiles # List profiles and counts ogham stats # Profile statistics ogham export -o backup.json # Export memories (JSON) ogham export --format markdown # Export as Obsidian-compatible markdown ogham export --format okf # Export as Open Knowledge Format v0.1 bundle ogham import backup.json # Import a JSON export ogham import <okf-bundle-dir> # Import an OKF bundle directory (auto-detected) ogham import <dir> --with-graph # ...including its entities/ graph layer (opt-in) ogham cleanup # Remove expired memories ogham hooks install # Auto-detect client + configure hooks ogham hooks recall # Read from the stone (load project context) ogham hooks inscribe # Carve into the stone (capture activity) ogham hooks inscribe --dry-run # Preview hook memory without storing ogham serve # Start MCP server (stdio, default) ogham serve --transport http # Start HTTP server on port 8742 ogham openapi # Generate OpenAPI spec

# MCP tool hybrid_search(query="architecture decisions", profiles=["work", "shared"]) # Python library from ogham.service import search_memories_enriched results = search_memories_enriched( query="architecture decisions", profile="work", profiles=["work", "shared", "project-alpha"], )

Whenprofilesis set, results include memories from all listed profiles with aprofilefield showing which profile each result came from.

EMBEDDING_DIMmust match thevector(N)column in your database schema. The default schema usesvector(512). If you use Mistral, you need to alter the column tovector(1024)before storing anything.

Each provider clusters vectors differently, so the similarity threshold matters. Start with the recommended value and adjust based on your results.

Temporal search-- queries with time expressions like "last week" or "three months ago" are resolved automatically using parsedatetime, no configuration needed. This handles roughly 80% of temporal queries at zero cost. For expressions parsedatetime cannot parse ("the quarter before last", "around Thanksgiving"), setTEMPORAL_LLM_MODELto call an LLM as a fallback:

# Self-hosted with Ollama (free, local) TEMPORAL_LLM_MODEL=ollama/llama3.2 # Cloud API TEMPORAL_LLM_MODEL=gpt-4o-mini

Anylitellm-compatible model string works --deepseek/deepseek-chat,moonshot/moonshot-v1-8k, etc. The LLM is only called when parsedatetime fails and the query has temporal intent, so costs stay near zero. IfTEMPORAL_LLM_MODELis empty (the default), parsedatetime handles everything on its own. Requires thelitellmpackage.

OGHAM_RECALL_ENABLED=false ogham serve # no context injection / memory search OGHAM_INSCRIBE_ENABLED=false ogham serve # no memory capture / content writes ogham hooks recall --no-recall # one-off hook recall skip ogham hooks inscribe --no-inscribe # one-off hook capture skip ogham search "query" --no-recall # one-off CLI search skip ogham store "some fact" --no-inscribe # one-off CLI store skip

{ "mcpServers": { "ogham": { "command": "ogham-serve", "env": { "OGHAM_RECALL_ENABLED": "false", "OGHAM_INSCRIBE_ENABLED": "false" } } } }

Typed-edge graph (v0.16)-- structural, typed relationships for two-fact join queries. Full detail in/docs/typed-edges/.

store_triple(subject="error:ValueError", ...) # exactly the error node store_triple(subject="ValueError", ...) # lowest-id match, and logs the collision

It is deliberatelynota confidence score. Calibration is a property of an estimated probability (Guo, Pleiss, Sun and Weinberger, ICML 2017); a fixed class per rule estimates nothing, so a float here would invite consumers to multiply it into a relevance score as though it meant something. It is an enumerated value with aCHECKconstraint.

Existing entities are classified from their type on upgrade. Nothing in retrieval reads it yet -- it exists so that when enrichment does start writing entities, a machine-suggested one is distinguishable from adapter-derived fact.