ogham-mcp

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.

Manual setup

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.sql for Supabase, sql/schema_postgres.sql for Neon/self-hosted), then add the MCP server to your client.

Installation methods

Method	Command	When to use
uvx (recommended)	uvx ogham-mcp	Quick setup, auto-updates
Docker	docker pull ghcr.io/ogham-mcp/ogham-mcp	Isolation, self-hosted
Git clone	git clone + uv sync	Development, contributions

Claude Code

claude mcp add ogham -- uvx ogham-mcp

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

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

From source

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

HTTP transport (multi-agent)

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.

Client config (any MCP client):

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

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

In Docker, bind to all interfaces. The default host is 127.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

SSE (legacy)

Ogham still accepts --transport sse and 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 an Mcp-Session-Id and 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.

Entry points

• ogham -- the CLI. Use this for ogham init, ogham health, ogham search, and other commands you run yourself. Running ogham with no arguments starts the MCP server.
• ogham-serve -- starts the MCP server directly. This is what MCP clients should call. When you run uvx ogham-mcp, it invokes ogham-serve.

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).

85.8% QA accuracy on the AMB 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 the Vectorize team (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 the full write-up for methodology differences.

0.554 nugget score on BEAM 100K (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.

End-to-end QA accuracy on LongMemEval (retrieval + LLM reads and answers):

System	Accuracy	Architecture
OMEGA	95.4%	Classification + extraction pipeline
Observational Memory (Mastra)	94.9%	Observation extraction + GPT-5-mini
Ogham v0.9.2	85.8%	Verbatim + read-time extraction + gpt-5-mini (AMB harness, strict judge)
Ogham v0.9.1	91.8%	Hybrid search + context engineering + gpt-5.4-mini (internal benchmark)
Hindsight (Vectorize)	91.4%	4 memory types + Gemini-3
Zep (Graphiti)	71.2%	Temporal knowledge graph + GPT-4o
Mem0	49.0%	RAG-based

Retrieval only (R@10 -- no LLM in the search loop):

System	R@10	Architecture
Ogham	97.2%	1 SQL query (pgvector + tsvector CCF hybrid search)
LongMemEval paper baseline	78.4%	Session decomposition + fact-augmented keys

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. Optional FlashRank reranking is available for self-hosters who want extra ranking precision.

These tables measure different things. QA accuracy tests whether the full system (retrieval + LLM) produces the correct answer. R@10 tests whether retrieval alone finds the right memories. Ogham is a retrieval engine -- it finds the memories, your LLM reads them.

Category	R@10	Questions
single-session-assistant	100%	56
knowledge-update	100%	78
single-session-user	98.6%	70
multi-session	97.3%	133
single-session-preference	96.7%	30
temporal-reasoning	93.5%	133

Full breakdown: ogham-mcp.dev/features

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.