Ogham Mcp

Ogham MCP

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

[](https://opensource.org/licenses/MIT) [](https://github.com/ogham-mcp/ogham-mcp/pkgs/container/ogham-mcp) [](https://python.org) [](https://pypi.org/project/ogham-mcp/)

Contents

• [Retrieval quality](#retrieval-quality) -- 97.2% R@10 on LongMemEval
• [The problem](#the-problem)
• [Quick start](#quick-start)
• [Installation methods](#installation-methods) -- Claude Code, OpenCode, Docker, source
• [SSE transport](#sse-transport-multi-agent) -- multi-agent setup
• [CLI](#cli) -- command-line interface
• [Configuration](#configuration) -- env vars, embedding providers, temporal search, lifecycle hooks
• [MCP tools](#mcp-tools) -- memory, search, graph, profiles, import/export
• [Wiki layer](#wiki-layer) -- synthesize topics, walk the graph, lint health
• [Obsidian export](#obsidian-export) -- snapshot your wiki to a vault of plain markdown
• [Open Knowledge Format](#open-knowledge-format) -- portable round-trip bundles with offline graph viewer
• [Skills](#skills) -- ogham-research, ogham-recall, ogham-maintain
• [Scoring and condensing](#scoring-and-condensing)
• [Cross-encoder reranking](#cross-encoder-reranking) -- optional FlashRank for self-hosters
• [ONNX local embeddings](#onnx-local-embeddings) -- BGE-M3 dense + sparse, no API costs
• [Database setup](#database-setup) -- Supabase, Neon, vanilla Postgres
• [Upgrading from v0.4.x](#upgrading-from-v04x)
• [Architecture](#architecture)

Retrieval quality

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](#cross-encoder-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

The problem

AI coding agents forget everything between sessions. Switch from Claude Code to Cursor to Kiro to OpenCode and context is lost. Decisions, gotchas, architectural patterns -- gone. You end up repeating yourself, re-explaining your codebase, re-debugging the same issues.

Ogham gives your agents a shared memory that persists across sessions and clients.

Quick start

1. Install

uvx --from ogham-mcp ogham init

This runs the setup wizard. It walks you through everything: database connection, embedding provider, schema migration, and writes MCP client configs for Claude Code, Cursor, VS Code, and others.

> You need a database before running this. Either create a free Supabase project or a Neon database. The wizard handles the rest.

> Using Neon or self-hosted Postgres? Install with the postgres extra so the driver is available: > ``bash > uvx --from 'ogham-mcp[postgres]' ogham init > ``

2. Add to your MCP client

The wizard configures everything and writes your client config -- including all environment variables the server needs. For Claude Code, it runs claude mcp add automatically. For other clients, copy the config snippet it prints.

3. Use it

Tell your agent to remember something, then ask about it later -- from the same client or a different one. It works because they all share the same database.

Manual setup (if you prefer)

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

SSE transport (multi-agent)

By default, Ogham runs in stdio mode -- each MCP client spawns its own server process. For multiple agents sharing one server, use SSE mode:

ogham serve --transport sse --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 for SSE (any MCP client):

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

Health check at http://127.0.0.1:8742/health (cached, sub-10ms).

Configure via env vars (OGHAM_TRANSPORT=sse, OGHAM_HOST, OGHAM_PORT) or CLI flags. The init wizard (ogham init) walks through SSE setup if you choose it.

Entry points

Ogham has two 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.

CLI

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                # Delete a memory by ID
ogham use              # 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    # Import an OKF bundle directory (auto-detected)
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 sse     # Start SSE server on port 8742
ogham openapi                   # Generate OpenAPI spec

Multi-profile search

Search across multiple profiles in a single query (v0.8.5+):

# 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"],
)

When profiles is set, results include memories from all listed profiles with a profile field showing which profile each result came from.

Configuration

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | DATABASE_BACKEND | No | supabase | supabase or postgres | | SUPABASE_URL | If supabase | -- | Your Supabase project URL | | SUPABASE_KEY | If supabase | -- | Supabase secret key (service_role) | | DATABASE_URL | If postgres | -- | PostgreSQL connection string | | EMBEDDING_PROVIDER | No | ollama | ollama, openai, mistral, voyage, gemini, or onnx | | EMBEDDING_DIM | No | 512 | Vector dimensions -- must match your schema (see below) | | OPENAI_API_KEY | If openai | -- | OpenAI API key | | MISTRAL_API_KEY | If mistral | -- | Mistral API key | | VOYAGE_API_KEY | If voyage | -- | Voyage AI API key | | GEMINI_API_KEY | If gemini | -- | Google Gemini API key | | OLLAMA_URL | No | http://localhost:11434 | Ollama server URL | | OLLAMA_EMBED_MODEL | No | embeddinggemma | Ollama embedding model | | MISTRAL_EMBED_MODEL | No | mistral-embed | Mistral embedding model | | VOYAGE_EMBED_MODEL | No | voyage-4-lite | Voyage embedding model | | GEMINI_EMBED_MODEL | No | gemini-embedding-2-preview | Gemini embedding model | | RERANK_ENABLED | No | false | Enable FlashRank cross-encoder reranking | | RERANK_ALPHA | No | 0.55 | Cross-encoder score weight (0-1) | | DEFAULT_MATCH_THRESHOLD | No | 0.7 | Similarity threshold (see below) | | DEFAULT_MATCH_COUNT | No | 10 | Max results per search | | DEFAULT_PROFILE | No | default | Memory profile name | | OGHAM_RECALL_ENABLED | No | true | Enable memory recall/context retrieval | | OGHAM_INSCRIBE_ENABLED | No | true | Enable memory capture/content writes |

Embedding providers

| Provider | Default dimensions | Recommended threshold | Notes | |----------|-------------------|----------------------|-------| | OpenAI | 512 (schema default) | 0.35 | Set EMBEDDING_DIM=512 explicitly -- OpenAI defaults to 1024 | | Ollama | 512 | 0.70 | Tight clustering, scores run 0.8-0.9 | | Mistral | 1024 | 0.60 | Fixed 1024 dims, can't truncate. Schema must be vector(1024) | | Voyage | 512 (schema default) | 0.45 | Moderate spread | | Gemini | 512 | 0.35 | gemini-embedding-2-preview, supports MRL truncation | | ONNX | 1024 | 0.35 | Local BGE-M3 inference, dense + sparse vectors. See [ONNX section](#onnx-local-embeddings) |

EMBEDDING_DIM must match the vector(N) column in your database schema. The default schema uses vector(512). If you use Mistral, you need to alter the column to vector(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

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 that parsedatetime cannot parse ("the quarter before last", "around Thanksgiving"), set TEMPORAL_LLM_MODEL to 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

Any litellm-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.

If TEMPORAL_LLM_MODEL is empty (the default), parsedatetime handles everything on its own. Requires the litellm package (pip install litellm or install Ogham with the appropriate extra).

Lifecycle hooks

Ogham hooks inject memory context at session start and preserve it across compaction. Install for your client:

ogham hooks install

| Client | What gets installed | |--------|-------------------| | Claude Code | Hooks in ~/.claude/settings.json (recall on SessionStart/PostCompact, inscribe on PostToolUse/PreCompact) | | Kiro | Instructions for Hook UI (recall on Prompt Submit, inscribe on Agent Stop) | | Codex, Cursor, others | Project instruction file (CLAUDE.md, AGENTS.md, or .cursorrules) |

Two commands, named after the Ogham stones:

• recall -- read from the stone. Searches Ogham for memories relevant to your project and injects them as context. Fires a

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ogham-mcp
• Source: ogham-mcp/ogham-mcp
• License: MIT
• Homepage: https://ogham-mcp.dev

Install and usage instructions live in the source repository linked above.