Ogham MCP

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

What it is

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 a retrieval engine: it stores what matters and finds it again, and your LLM reads the results.

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

Quick start

uvx --from ogham-mcp ogham init

ogham init runs 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 runs claude mcp add for you; for other clients it prints the snippet to copy.

You need a database first – a free Supabase project or a Neon database. 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.

Retrieval quality

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 LongMemEval with one Postgres query (pgvector + tsvector CCF hybrid search). The paper baseline 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 the AMB harness (500 questions, April 2026, strict substring judge, GPT-5-mini reader; R@10 99.5%), and 0.554 nugget on BEAM 100K (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 at ogham-mcp.dev/features; the write-ups explain why the AMB and internal numbers differ (LongMemEval, BEAM).

How it works

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

Memories are stored as rows with vector embeddings. Search combines pgvector cosine similarity with PostgreSQL full-text search using Reciprocal Rank Fusion (RRF) – position-based, score-agnostic fusion that handles different score scales correctly. The knowledge graph lives in a memory_relationships table walked with recursive CTEs; the typed-edge graph (v0.16) adds structural, predicate-typed relationships for two-fact join queries. No separate graph database. Optional FlashRank cross-encoder reranking adds a second pass for self-hosters.

What’s in it

• 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_join for 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 in Reference below.

The deeper story

The retrieval pipeline is built on established information-retrieval and cognitive-science work, not ad-hoc heuristics:

• 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 an audit_log table in the same Postgres instance, aligned with GDPR Article 15 and OTEL GenAI conventions.

---

Reference

Documentation

Full docs and integration guides at ogham-mcp.dev.

Credits

Inspired by Nate B Jones and his work on persistent AI memory.

Named after Ogham, the ancient Irish alphabet carved into stone – the original persistent memory.

License

MIT