Skip to content
Back to search

ogham-mcp

Shared memory MCP server — persistent, searchable, cross-client Claude, Opencode

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/ogham-mcp--ogham-mcp/badge.svg)](/listings/ogham-mcp--ogham-mcp)

HTML

<a href="/listings/ogham-mcp--ogham-mcp"><img src="/api/listings/ogham-mcp--ogham-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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](https://supabase.com) project or a [Neon](https://neon.tech) 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.

<details> <summary><b>Manual setup, other install methods (Docker, source), HTTP multi-agent mode</b></summary>

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.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 928 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Ogham MCP
  2. *Ogham* (pronounced "OH-um") -- persistent, searchable shared memory for AI coding agents. Works across clients.
  3. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
  4. [![Docker](https://img.shields.io/badge/Docker-ghcr.io%2Fogham--mcp%2Fogham--mcp-blue)](https://github.com/ogham-mcp/ogham-mcp/pkgs/container/ogham-mcp)
  5. [![Python 3.13+](https://img.shields.io/badge/Python-3.13%2B-blue)](https://python.org)
  6. [![PyPI](https://img.shields.io/pypi/v/ogham-mcp)](https://pypi.org/project/ogham-mcp/)
  7. ## What it is
  8. 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.
  9. 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.
  10. 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.
  11. ## Quick start
  12. ```bash
  13. uvx --from ogham-mcp ogham init
  14. ```
  15. `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.
  16. **You need a database first** -- a free [Supabase](https://supabase.com) project or a [Neon](https://neon.tech) database. On Neon or self-hosted Postgres, install the postgres extra so the driver is available:
  17. ```bash
  18. uvx --from 'ogham-mcp[postgres]' ogham init
  19. ```
  20. 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.
  21. <details>
  22. <summary><b>Manual setup, other install methods (Docker, source), HTTP multi-agent mode</b></summary>
  23. ### Manual setup
  24. If you'd rather configure things yourself instead of using the wizard:
  25. ```bash
  26. # Supabase
  27. export SUPABASE_URL=https://your-project.supabase.co
  28. export SUPABASE_KEY=your-service-role-key
  29. export EMBEDDING_PROVIDER=openai # or ollama, mistral, voyage
  30. export OPENAI_API_KEY=sk-... # for your chosen provider
  31. # Or Postgres (Neon, self-hosted)
  32. export DATABASE_BACKEND=postgres
  33. export DATABASE_URL=postgresql://user:pass@host/db
  34. export EMBEDDING_PROVIDER=openai
  35. export OPENAI_API_KEY=sk-...
  36. ```
  37. 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.
  38. ### Installation methods
  39. | Method | Command | When to use |
  40. |--------|---------|-------------|
  41. | **uvx** (recommended) | `uvx ogham-mcp` | Quick setup, auto-updates |
  42. | **Docker** | `docker pull ghcr.io/ogham-mcp/ogham-mcp` | Isolation, self-hosted |
  43. | **Git clone** | `git clone` + `uv sync` | Development, contributions |
  44. #### Claude Code
  45. ```bash
  46. claude mcp add ogham -- uvx ogham-mcp
  47. ```
  48. **OpenCode** -- add to `~/.config/opencode/opencode.json`:
  49. ```json
  50. {
  51. "mcp": {
  52. "ogham": {
  53. "type": "local",
  54. "command": ["uvx", "ogham-mcp"],
  55. "environment": {
  56. "SUPABASE_URL": "https://your-project.supabase.co",
  57. "SUPABASE_KEY": "{env:SUPABASE_KEY}",
  58. "EMBEDDING_PROVIDER": "openai",
  59. "OPENAI_API_KEY": "{env:OPENAI_API_KEY}"
  60. }
  61. }
  62. }
  63. }
  64. ```
  65. #### Docker
  66. ```bash
  67. docker run --rm \
  68. -e SUPABASE_URL=https://your-project.supabase.co \
  69. -e SUPABASE_KEY=your-key \
  70. -e EMBEDDING_PROVIDER=openai \
  71. -e OPENAI_API_KEY=sk-... \
  72. ghcr.io/ogham-mcp/ogham-mcp
  73. ```
  74. #### From source
  75. ```bash
  76. git clone https://github.com/ogham-mcp/ogham-mcp.git
  77. cd ogham-mcp
  78. uv sync
  79. uv run ogham --help
  80. ```
  81. ### HTTP transport (multi-agent)
  82. 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:
  83. ```bash
  84. ogham serve --transport streamable-http --port 8742
  85. ```
  86. The server runs as a persistent background process. All clients connect to the same instance -- one database pool, one embedding cache, shared memory.
  87. Client config (any MCP client):
  88. ```json
  89. {
  90. "mcpServers": {
  91. "ogham": {
  92. "url": "http://127.0.0.1:8742/mcp"
  93. }
  94. }
  95. }
  96. ```
  97. 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`.
  98. **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:
  99. ```bash
  100. docker run -p 8742:8742 ghcr.io/ogham-mcp/ogham-mcp:latest \
  101. serve --transport streamable-http --host 0.0.0.0 --port 8742
  102. ```
  103. #### SSE (legacy)
  104. 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.
  105. 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.
  106. ### Entry points
  107. - **`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.
  108. - **`ogham-serve`** -- starts the MCP server directly. This is what MCP clients should call. When you run `uvx ogham-mcp`, it invokes `ogham-serve`.
  109. </details>
  110. ## Retrieval quality
  111. Ogham is a retrieval engine -- it finds the memories, your LLM reads them. The headline numbers, and they measure different things:
  112. - **Retrieval:** **97.2% R@10 on LongMemEval** with **one Postgres query** (pgvector + tsvector CCF hybrid search). The [paper](https://arxiv.org/abs/2410.10813) baseline is 78.4%. Other systems that report similar R@10 typically stack cross-encoder reranking, NLI verification, and knowledge-graph enrichment.
  113. - **End-to-end QA:** **85.8% on the [AMB harness](https://github.com/vectorize-io/agent-memory-benchmark)** (500 questions, April 2026, strict substring judge, GPT-5-mini reader; R@10 99.5%), and **0.554 nugget on [BEAM](https://arxiv.org/abs/2510.27246) 100K** (paper baseline 0.358; seven of nine categories beat the paper).
  114. 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](https://ogham-mcp.dev/features/#retrieval-quality); the write-ups explain why the AMB and internal numbers differ ([LongMemEval](https://ogham-mcp.dev/blog/longmemeval-92/), [BEAM](https://ogham-mcp.dev/blog/beam-benchmark-v090/)).
  115. <details>
  116. <summary><b>Full benchmark tables (QA, R@10, per-category, competitors)</b></summary>
  117. **85.8% QA accuracy on the [AMB benchmark harness](https://github.com/vectorize-io/agent-memory-benchmark)** (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](https://vectorize.io) team (creators of Hindsight). Thanks to Nicolo and the Vectorize team for making the harness open.
  118. 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](https://ogham-mcp.dev/blog/longmemeval-92/) for methodology differences.
  119. **0.554 nugget score on [BEAM](https://arxiv.org/abs/2510.27246) 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](https://ogham-mcp.dev/blog/beam-benchmark-v090/).
  120. **End-to-end QA accuracy** on LongMemEval (retrieval + LLM reads and answers):
  121. | System | Accuracy | Architecture |
  122. |--------|----------|-------------|
  123. | [OMEGA](https://dev.to/singularityjason/how-i-built-a-memory-system-that-scores-954-on-longmemeval-1-on-the-leaderboard-2md3) | 95.4% | Classification + extraction pipeline |
  124. | [Observational Memory (Mastra)](https://mastra.ai/research/observational-memory) | 94.9% | Observation extraction + GPT-5-mini |
  125. | **Ogham v0.9.2** | **85.8%** | Verbatim + read-time extraction + gpt-5-mini (AMB harness, strict judge) |
  126. | Ogham v0.9.1 | 91.8% | Hybrid search + context engineering + gpt-5.4-mini (internal benchmark) |
  127. | [Hindsight (Vectorize)](https://venturebeat.com/data/with-91-accuracy-open-source-hindsight-agentic-memory-provides-20-20-vision) | 91.4% | 4 memory types + Gemini-3 |
  128. | [Zep (Graphiti)](https://blog.getzep.com/state-of-the-art-agent-memory/) | 71.2% | Temporal knowledge graph + GPT-4o |
  129. | [Mem0](https://mem0.ai) | 49.0% | RAG-based |
  130. **Retrieval only** (R@10 -- no LLM in the search loop):
  131. | System | R@10 | Architecture |
  132. |--------|------|-------------|
  133. | **Ogham** | **97.2%** | 1 SQL query (pgvector + tsvector CCF hybrid search) |
  134. | [LongMemEval paper](https://arxiv.org/abs/2410.10813) baseline | 78.4% | Session decomposition + fact-augmented keys |
  135. 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](#reference) is available for self-hosters who want extra ranking precision.
  136. 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.
  137. | Category | R@10 | Questions |
  138. |----------|------|-----------|
  139. | single-session-assistant | 100% | 56 |
  140. | knowledge-update | 100% | 78 |
  141. | single-session-user | 98.6% | 70 |
  142. | multi-session | 97.3% | 133 |
  143. | single-session-preference | 96.7% | 30 |
  144. | temporal-reasoning | 93.5% | 133 |
  145. Full breakdown: [ogham-mcp.dev/features](https://ogham-mcp.dev/features/#retrieval-quality)
  146. </details>
  147. ## How it works
  148. ```text
  149. AI Client (Claude Code, Cursor, Kiro, OpenCode, ...)
  150. |
  151. | stdio or SSE (MCP protocol)
  152. |
  153. Ogham MCP Server
  154. |
  155. | HTTPS (Supabase REST API) or direct connection (Postgres)
  156. |
  157. PostgreSQL + pgvector
  158. ```
  159. 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.
  160. ## What's in it
  161. - **Memory operations** -- store memories, decisions, preferences, facts, and events; update, reinforce, and contradict.
  162. - **Hybrid search** -- semantic + full-text (RRF), tag filters, multi-profile search, read-time fact extraction.
  163. - **Typed-edge graph (v0.16)** -- `store_triple` / `query_join` for two-fact join queries against a controlled predicate vocabulary. [docs](https://ogham-mcp.dev/docs/typed-edges/)
  164. - **Knowledge graph** -- auto-linking, spreading-activation retrieval, and connection suggestions via shared entities.
  165. - **Wiki layer** -- synthesize a tag's memories into a cached markdown page; walk the graph; lint health.
  166. - **Open Knowledge Format** -- portable round-trip bundles (markdown + a self-contained graph viewer), OKF v0.1.
  167. - **Entity enrichment** -- regex entity tags across 18 languages with no LLM in the write path; a timeline table; Lost-in-the-Middle reordering.
  168. - **Memory lifecycle** -- FRESH / STABLE / EDITING stages, ACT-R importance, Hebbian decay, and automatic condensing.
  169. - **Importers** -- Claude Code auto-memory, Claude.ai export, Linear issues, and JSON.
  170. - **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.
  171. - **Lifecycle hooks** -- recall context at session start, inscribe signal (not noise) after tool use; secrets masked before storage.
  172. - **Skills** -- `ogham-research`, `ogham-recall`, `ogham-maintain`.
  173. - **Self-hoster options** -- ONNX local embeddings (BGE-M3), optional FlashRank reranking, five embedding providers.
  174. Full reference for every tool, env var, and setup path is in [Reference](#reference) below.
  175. ## The deeper story
  176. The retrieval pipeline is built on established information-retrieval and cognitive-science work, not ad-hoc heuristics:
  177. - **Hybrid search** -- Reciprocal Rank Fusion ([Cormack, Clarke & Butt, SIGIR 2009](https://dl.acm.org/doi/10.1145/1571941.1572114)): dense vector similarity rank-fused with BM25-style keyword matching, no score normalisation.
  178. - **ACT-R importance + Hebbian decay** -- recency, frequency, and surprise weighting ([Anderson & Lebiere, 1998](https://act-r.psy.cmu.edu/about/); [Hebb, 1949](https://doi.org/10.4324/9781315735368)). Unaccessed memories fade; frequently accessed ones potentiate and persist.
  179. - **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](https://arxiv.org/abs/2510.05179)). Supports local models via Ollama for full data sovereignty.
  180. - **Contradiction detection + supersession** -- opposite-polarity memories are linked, not deleted; the edge records that the newer memory superseded the older one.
  181. - **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](https://opentelemetry.io/docs/specs/semconv/gen-ai/gen-ai-spans/).
  182. <details>
  183. <summary><b>Research foundations (full list with citations)</b></summary>
  184. Ogham's retrieval pipeline combines established information retrieval and cognitive science techniques:
  185. - **Hybrid search** -- Reciprocal Rank Fusion ([Cormack, Clarke & Butt, SIGIR 2009](https://dl.acm.org/doi/10.1145/1571941.1572114)) combining dense vector similarity (pgvector) with BM25-style keyword matching (PostgreSQL tsvector). Two independent retrieval systems, rank-fused without score normalisation.
  186. - **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](https://aclanthology.org/K18-1050/)). Entity extraction covers 18 languages via YAML-based word lists with no LLM in the write path.
  187. - **Matryoshka embeddings** -- flexible dimensionality via Matryoshka Representation Learning ([Kusupati et al., NeurIPS 2022](https://arxiv.org/abs/2205.13147)). Embedding providers (OpenAI, Voyage, Gemini, Ollama) produce native-dimension vectors truncated to 512d, enabling provider-portable storage without re-embedding.
  188. - **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](https://dl.acm.org/doi/10.1145/290941.291025)). Only activates when the top-k results are temporally concentrated, leaving well-distributed results untouched.
  189. - **ACT-R importance scoring** -- cognitive-architecture-inspired memory weighting based on recency, access frequency, and surprise ([Anderson & Lebiere, 1998](https://act-r.psy.cmu.edu/about/)). Frequently accessed memories stay sharp, rarely accessed ones fade, disputed ones drop in ranking without deletion.
  190. - **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](https://doi.org/10.4324/9781315735368)) and computational models of synaptic plasticity ([Bi & Poo, 2001](https://doi.org/10.1146/annurev.neuro.24.1.139)). 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 via `ogham decay` or pg_cron.
  191. - **Memory lifecycle (v0.11.0): FRESH / STABLE / EDITING.** Every memory
  192. now has an explicit stage tracked in a dedicated `memory_lifecycle`
  193. table. New memories land at `fresh`. The session-start hook sweeps
  194. aged fresh memories to `stable` when they clear an importance-or-surprise
  195. gate and have dwelled long enough. Retrieval opens a 30-minute
  196. `editing` window on the returned memories so follow-up
  197. `update_memory` calls refine recent thoughts in place; windows
  198. auto-close on the next sweep. Memories retrieved together also
  199. strengthen their pairwise graph edges (eta=0.01 per co-retrieval,
  200. capped at 1.0). The design draws on three lines of prior art:
  201. Hebbian co-activation ([Hebb, 1949](https://doi.org/10.4324/9781315735368)),
  202. the hybrid exponential-then-power-law forgetting curve characterised
  203. by [Wixted (2004)](https://doi.org/10.1146/annurev.psych.55.090902.141555)
  204. building on [Ebbinghaus (1885)](https://psychclassics.yorku.ca/Ebbinghaus/memory1.htm),
  205. and the memory reconsolidation window from neuroscience
  206. ([Nader, Schafe & LeDoux, 2000](https://doi.org/10.1038/35021052))
  207. for the editing-on-retrieval mechanic. Stage state lives in its
  208. own table so transitions do not touch the HNSW vector index.
  209. - **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](https://doi.org/10.1037/0033-295X.82.6.407)) semantic network theory.
  210. - **Contradiction detection** -- when a new memory has opposite polarity to a high-similarity existing memory, Ogham automatically creates a `contradicts` relationship edge. Polarity detection uses negation markers across 18 languages loaded from YAML word lists. Contradicted memories are not deleted -- the edge records that the newer memory superseded the older one.
  211. - **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](https://arxiv.org/abs/2510.05179)). Supports local models via Ollama for full data sovereignty.
  212. - **Append-only audit trails** -- every store, search, delete, and update operation is logged to an `audit_log` table in the same Postgres instance. Designed for GDPR Article 15 subject access requests and cost governance. Fields align with [OTEL GenAI Semantic Conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/gen-ai-spans/). Query via `ogham audit` CLI. No extra infrastructure -- runs in the same database as memories.
  213. </details>
  214. ---
  215. ## Reference
  216. <details>
  217. <summary><b>CLI commands</b></summary>
  218. ```bash
  219. ogham init # Interactive setup wizard
  220. ogham health # Check database + embedding provider
  221. ogham config # Show runtime configuration (secrets masked)
  222. ogham store "some fact" # Store a memory
  223. ogham search "query" # Search memories (hybrid: semantic + keyword)
  224. ogham search "q" --json # JSON output for scripting
  225. ogham search "q" --tags "a,b" # Filter by comma-separated tags
  226. ogham list # List recent memories
  227. ogham list --json # JSON output
  228. ogham delete <id> # Delete a memory by ID
  229. ogham use <profile> # Switch default profile
  230. ogham profiles # List profiles and counts
  231. ogham stats # Profile statistics
  232. ogham export -o backup.json # Export memories (JSON)
  233. ogham export --format markdown # Export as Obsidian-compatible markdown
  234. ogham export --format okf # Export as Open Knowledge Format v0.1 bundle
  235. ogham import backup.json # Import a JSON export
  236. ogham import <okf-bundle-dir> # Import an OKF bundle directory (auto-detected)
  237. ogham import <dir> --with-graph # ...including its entities/ graph layer (opt-in)
  238. ogham cleanup # Remove expired memories
  239. ogham hooks install # Auto-detect client + configure hooks
  240. ogham hooks recall # Read from the stone (load project context)
  241. ogham hooks inscribe # Carve into the stone (capture activity)
  242. ogham hooks inscribe --dry-run # Preview hook memory without storing
  243. ogham serve # Start MCP server (stdio, default)
  244. ogham serve --transport http # Start HTTP server on port 8742
  245. ogham openapi # Generate OpenAPI spec
  246. ```
  247. **Multi-profile search** -- search across multiple profiles in a single query (v0.8.5+):
  248. ```python
  249. # MCP tool
  250. hybrid_search(query="architecture decisions", profiles=["work", "shared"])
  251. # Python library
  252. from ogham.service import search_memories_enriched
  253. results = search_memories_enriched(
  254. query="architecture decisions",
  255. profile="work",
  256. profiles=["work", "shared", "project-alpha"],
  257. )
  258. ```
  259. When `profiles` is set, results include memories from all listed profiles with a `profile` field showing which profile each result came from.
  260. </details>
  261. <details>
  262. <summary><b>Configuration (env vars, embedding providers, temporal search)</b></summary>
  263. | Variable | Required | Default | Description |
  264. |----------|----------|---------|-------------|
  265. | `DATABASE_BACKEND` | No | `supabase` | `supabase` or `postgres` |
  266. | `SUPABASE_URL` | If supabase | -- | Your Supabase project URL |
  267. | `SUPABASE_KEY` | If supabase | -- | Supabase secret key (service_role) |
  268. | `DATABASE_URL` | If postgres | -- | PostgreSQL connection string |
  269. | `EMBEDDING_PROVIDER` | No | `ollama` | `ollama`, `openai`, `mistral`, `voyage`, `gemini`, or `onnx` |
  270. | `EMBEDDING_DIM` | No | `512` | Vector dimensions -- must match your schema (see below) |
  271. | `OPENAI_API_KEY` | If openai | -- | OpenAI API key |
  272. | `MISTRAL_API_KEY` | If mistral | -- | Mistral API key |
  273. | `VOYAGE_API_KEY` | If voyage | -- | Voyage AI API key |
  274. | `GEMINI_API_KEY` | If gemini | -- | Google Gemini API key |
  275. | `OLLAMA_URL` | No | `http://localhost:11434` | Ollama server URL |
  276. | `OLLAMA_EMBED_MODEL` | No | `embeddinggemma` | Ollama embedding model |
  277. | `MISTRAL_EMBED_MODEL` | No | `mistral-embed` | Mistral embedding model |
  278. | `VOYAGE_EMBED_MODEL` | No | `voyage-4-lite` | Voyage embedding model |
  279. | `GEMINI_EMBED_MODEL` | No | `gemini-embedding-2` | Gemini embedding model |
  280. | `RERANK_ENABLED` | No | `false` | Enable FlashRank cross-encoder reranking |
  281. | `RERANK_ALPHA` | No | `0.55` | Cross-encoder score weight (0-1) |
  282. | `DEFAULT_MATCH_THRESHOLD` | No | `0.7` | Similarity threshold (see below) |
  283. | `DEFAULT_MATCH_COUNT` | No | `10` | Max results per search |
  284. | `DEFAULT_PROFILE` | No | `default` | Memory profile name |
  285. | `OGHAM_RECALL_ENABLED` | No | `true` | Enable memory recall/context retrieval |
  286. | `OGHAM_INSCRIBE_ENABLED` | No | `true` | Enable memory capture/content writes |
  287. ### Embedding providers
  288. | Provider | Default dimensions | Recommended threshold | Notes |
  289. |----------|-------------------|----------------------|-------|
  290. | OpenAI | 512 (schema default) | 0.35 | Set `EMBEDDING_DIM=512` explicitly -- OpenAI defaults to 1024 |
  291. | Ollama | 512 | 0.70 | Tight clustering, scores run 0.8-0.9 |
  292. | Mistral | 1024 | 0.60 | Fixed 1024 dims, can't truncate. Schema must be `vector(1024)` |
  293. | Voyage | 512 (schema default) | 0.45 | Moderate spread |
  294. | Gemini | 512 | 0.35 | `gemini-embedding-2`, supports MRL truncation |
  295. | ONNX | 1024 | 0.35 | Local BGE-M3 inference, dense + sparse vectors. See ONNX section |
  296. `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.
  297. Each provider clusters vectors differently, so the similarity threshold matters. Start with the recommended value and adjust based on your results.
  298. **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"), set `TEMPORAL_LLM_MODEL` to call an LLM as a fallback:
  299. ```bash
  300. # Self-hosted with Ollama (free, local)
  301. TEMPORAL_LLM_MODEL=ollama/llama3.2
  302. # Cloud API
  303. TEMPORAL_LLM_MODEL=gpt-4o-mini
  304. ```
  305. Any [litellm](https://docs.litellm.ai/docs/providers)-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.
  306. </details>
  307. <details>
  308. <summary><b>Lifecycle hooks (recall / inscribe, smart filtering, secret masking)</b></summary>
  309. Ogham hooks inject memory context at session start and preserve it across compaction. Install for your client:
  310. ```bash
  311. ogham hooks install
  312. ```
  313. | Client | What gets installed |
  314. |--------|-------------------|
  315. | Claude Code | Hooks in `~/.claude/settings.json` (recall on SessionStart/PostCompact, inscribe on PostToolUse/PreCompact) |
  316. | Kiro | Instructions for Hook UI (recall on Prompt Submit, inscribe on Agent Stop) |
  317. | Codex, Cursor, others | Project instruction file (CLAUDE.md, AGENTS.md, or .cursorrules) |
  318. ### Two commands, named after the Ogham stones
  319. - **recall** -- read from the stone. Searches Ogham for memories relevant to your project and injects them as context. Fires at session start and after compaction.
  320. - **inscribe** -- carve into the stone. Captures meaningful tool activity as memories. Skips noise (`ls`, `cat`, `git status`) and only stores signal (commits, deploys, errors, config changes). Fires after tool use and before compaction. Secrets are masked before storing.
  321. Disable either flow when you want an agent attached to Ogham without letting it pull memory into context or write new memory:
  322. ```bash
  323. OGHAM_RECALL_ENABLED=false ogham serve # no context injection / memory search
  324. OGHAM_INSCRIBE_ENABLED=false ogham serve # no memory capture / content writes
  325. ogham hooks recall --no-recall # one-off hook recall skip
  326. ogham hooks inscribe --no-inscribe # one-off hook capture skip
  327. ogham search "query" --no-recall # one-off CLI search skip
  328. ogham store "some fact" --no-inscribe # one-off CLI store skip
  329. ```
  330. For MCP clients, put the env vars in that client's Ogham server config:
  331. ```json
  332. {
  333. "mcpServers": {
  334. "ogham": {
  335. "command": "ogham-serve",
  336. "env": {
  337. "OGHAM_RECALL_ENABLED": "false",
  338. "OGHAM_INSCRIBE_ENABLED": "false"
  339. }
  340. }
  341. }
  342. }
  343. ```
  344. Admin operations such as config, health, stats, audit, export, delete, and cleanup remain available so you can inspect or clean memory even when recall or inscribe is disabled.
  345. **Smart filtering:** Hooks don't capture everything. Routine commands (`ls`, `pwd`, `git add`) are skipped. Only signal events (errors, deployments, commits, config changes) are stored -- typically 20-30 memories per session instead of hundreds.
  346. **Secret masking:** API keys, tokens, passwords, and JWTs are automatically replaced with `***MASKED***` before storing. The event is captured ("configured Stripe API key") but the actual secret never touches the database.
  347. </details>
  348. <details>
  349. <summary><b>MCP tools (memory, search, graph, typed-edge, importers, profiles, import/export, maintenance)</b></summary>
  350. ### Memory operations
  351. | Tool | Description | Key parameters |
  352. |------|-------------|----------------|
  353. | `store_memory` | Store a new memory with embedding | `content` (required), `source`, `tags[]`, `auto_link` |
  354. | `store_decision` | Store an architectural decision | `decision`, `reasoning`, `alternatives[]`, `tags[]` |
  355. | `store_preference` | Store a user preference with strength metadata | `preference`, `subject`, `alternatives[]`, `strength` |
  356. | `store_fact` | Store a factual statement with confidence and citation | `fact`, `subject`, `confidence`, `source_citation` |
  357. | `store_event` | Store an event with temporal and participant metadata | `event`, `when`, `participants[]`, `location` |
  358. | `update_memory` | Update content of existing memory | `memory_id`, `content`, `tags[]` |
  359. | `delete_memory` | Delete a memory by ID | `memory_id` |
  360. | `reinforce_memory` | Increase confidence score | `memory_id` |
  361. | `contradict_memory` | Decrease confidence score | `memory_id` |
  362. ### Search
  363. | Tool | Description | Key parameters |
  364. |------|-------------|----------------|
  365. | `hybrid_search` | Combined semantic + full-text search (RRF) | `query`, `limit`, `tags[]`, `graph_depth`, `profiles[]`, `extract_facts` |
  366. | `list_recent` | List recent memories | `limit`, `profile` |
  367. | `find_related` | Find memories related to a given one | `memory_id`, `limit` |
  368. ### Knowledge graph
  369. | Tool | Description | Key parameters |
  370. |------|-------------|----------------|
  371. | `link_unlinked` | Auto-link memories by embedding similarity | `threshold`, `limit` |
  372. | `explore_knowledge` | Traverse the knowledge graph | `memory_id`, `depth`, `direction` |
  373. | `suggest_connections` | Find hidden connections via shared entities | `memory_id`, `min_shared_entities`, `limit` |
  374. **Typed-edge graph (v0.16)** -- structural, typed relationships for two-fact join queries. Full detail in [`/docs/typed-edges/`](https://ogham-mcp.dev/docs/typed-edges/).
  375. | Tool | Description | Key parameters |
  376. |------|-------------|----------------|
  377. | `store_triple` | Write a typed edge against a controlled predicate vocabulary; supersedes the prior current edge for the same subject + predicate + object | `subject`, `predicate`, `object`, `profile`, `source_memory_id` |
  378. | `query_join` | Walk a typed predicate path from a start entity; returns the entities (BFS order), edges, and citations along the path -- no fuzzy ranking | `start_entity`, `predicate_path[]`, `hop_limit` (required), `direction` |
  379. **Referring to an entity (v0.19).** Entities are keyed on
  380. `(canonical_name, entity_type)`, so a bare name is not always enough to identify
  381. one. The same word can legitimately land under two types -- `ValueError` is both
  382. an `entity:` (interior capitalisation) and an `error:` (the `Error` suffix). Pass
  383. a qualified reference to be explicit:
  384. ```python
  385. store_triple(subject="error:ValueError", ...) # exactly the error node
  386. store_triple(subject="ValueError", ...) # lowest-id match, and logs the collision
  387. ```
  388. An unqualified reference still resolves, deterministically, and warns when it had
  389. to choose. Before v0.19 it chose silently.
  390. **Evidence class (v0.19).** Every entity now records **how it was established**:
  391. | class | meaning |
  392. |-------|---------|
  393. | `syntactic` | an unambiguous marker in the text -- interior capitalisation, a path separator, an `Error` suffix, a number with a unit |
  394. | `inferred` | a dictionary or keyword lookup with no marker -- places, events, preferences, emotions |
  395. | `structured` | derived from adapter provenance rather than from text |
  396. It is deliberately **not** a confidence score. Calibration is a property of an
  397. estimated probability ([Guo, Pleiss, Sun and Weinberger, ICML 2017](https://arxiv.org/abs/1706.04599));
  398. a fixed class per rule estimates nothing, so a float here would invite consumers
  399. to multiply it into a relevance score as though it meant something. It is an
  400. enumerated value with a `CHECK` constraint.
  401. Existing entities are classified from their type on upgrade. Nothing in retrieval
  402. reads it yet -- it exists so that when enrichment does start writing entities, a
  403. machine-suggested one is distinguishable from adapter-derived fact.
  404. ### Importers
  405. | Tool | Description | Key parameters |
  406. |------|-------------|----------------|
  407. | `import_linear` | Import Linear issues as memories, read-only, deduped by tracker id (v0.16) | see [`/docs/import-linear/`](https://ogham-mcp.dev/docs/import-linear/) |
  408. ### Profiles
  409. | Tool | Description | Key parameters |
  410. |------|-------------|----------------|
  411. | `switch_profile` | Switch active memory profile | `profile` |
  412. | `current_profile` | Show active profile | -- |
  413. | `list_profiles` | List all profiles with counts | -- |
  414. | `set_profile_ttl` | Set auto-expiry for a profile | `profile`, `ttl_days` |
  415. ### Import / export
  416. | Tool | Description | Key parameters |
  417. |------|-------------|----------------|
  418. | `export_profile` | Export all memories in active profile | `format` (`json`, `markdown`, or `okf`), `include_viewer` (default true for OKF) |
  419. | `import_memories_tool` | Import a JSON export string OR auto-detect an OKF bundle directory by path | `data`, `dedup_threshold` |
  420. **`--format okf`** writes an [Open Knowledge Format v0.1](https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve-data-sharing) conformant bundle: a directory of one-markdown-file-per-memory with YAML frontmatter, a bundle-root `index.md` declaring `okf_version: "0.1"`, and a self-contained `viewer.html` (Cytoscape.js graph, opens with `file://`, no server or CDN needed). Round-trip preserves UUID, content, tags, source, and metadata; the embedding is regenerated on import. Pass `include_viewer=false` to skip the HTML graph. See the [OKF round-trip write-up](https://ogham-mcp.dev/blog/okf-round-trip-v015/) for the background.
  421. ### Maintenance
  422. | Tool | Description | Key parameters |
  423. |------|-------------|----------------|
  424. | `re_embed_all` | Re-embed all memories (after switching providers) | -- |
  425. | `compress_old_memories` | Condense old inactive memories (full text to summary to tags) | -- |
  426. | `cleanup_expired` | Remove expired memories (TTL) | -- |
  427. | `health_check` | Check database and embedding connectivity | -- |
  428. | `get_config` | Show runtime configuration with masked secrets | -- |
  429. | `get_stats` | Memory counts, sources, tags, and profile health (orphans, decay, tagging) | -- |
  430. | `get_cache_stats` | Embedding cache hit rates | -- |
  431. </details>
  432. <details>
  433. <summary><b>Wiki layer</b></summary>
  434. The wiki layer turns a tag full of related memories into a synthesized markdown page. Run `compile_wiki` on a tag, get back a summarized topic; the cache invalidates automatically when underlying memories change. Four MCP tools cover the lifecycle:
  435. | Tool | Description | Key parameters |
  436. |------|-------------|----------------|
  437. | `compile_wiki` | Compile a tag's memories into a synthesized markdown page (LLM call, cached) | `topic`, `provider`, `model`, `force` |
  438. | `query_topic_summary` | Read the cached page for a topic without recomputing | `topic` |
  439. | `walk_knowledge` | Direction-aware graph walk from a known memory along relationship edges | `start_id`, `depth`, `direction` (`outgoing`, `incoming`, `both`), `min_strength`, `relationship_types` |
  440. | `lint_wiki` | Health report: contradictions, orphans, stale lifecycle, stale summaries, summary drift | `stable_days`, `sample_size`, `include_drift` |
  441. **The wiki layer needs an LLM.** Synthesis is the LLM step that turns a list of memories into a coherent page; embeddings alone aren't enough. You can run that LLM **locally** (Ollama with `llama3.2`, vLLM, or any OpenAI-compatible local server) or **in the cloud** (Gemini, OpenAI, Anthropic, Mistral, Groq, OpenRouter). Local keeps everything private and free; cloud generally writes more polished prose at the cost of a few cents per compile.
  442. Set the default with `LLM_PROVIDER` and `LLM_MODEL` in your environment (e.g. `LLM_PROVIDER=gemini` + `LLM_MODEL=gemini-2.5-flash`, or `LLM_PROVIDER=ollama` + `LLM_MODEL=llama3.2`). Override per call with `compile_wiki(topic=..., provider=..., model=...)`. The provider/model is stamped into the resulting page's frontmatter, so you can re-compile the same topic with a different LLM and see how the synthesis changes.
  443. `compile_wiki` short-circuits when the source memories haven't changed since the last compile -- the call is effectively free if nothing has moved. Pass `force=True` to bypass that check (useful for re-compiling with a different model on the same source set).
  444. The wiki layer requires migrations 028, 030, and 031 applied to your database. See Database setup for details.
  445. </details>
  446. <details>
  447. <summary><b>Obsidian export</b></summary>
  448. Snapshot your wiki layer to a folder of Obsidian-compatible markdown files. One `.md` per topic with full YAML frontmatter, plus a `README.md` index. Wikilinks between topics are auto-detected and wrapped in `[[brackets]]` for Obsidian's graph view.
  449. ```bash
  450. ogham export-obsidian /path/to/vault
  451. ogham export-obsidian /path/to/vault --profile work --force
  452. ```
  453. The export is read-only -- it writes files but never reads them back. Edits in Obsidian stay in Obsidian; re-run the export to refresh the snapshot. By design the exporter refuses to write into a directory that already contains files it didn't create; pass `--force` to override that guardrail.
  454. Full guide with frontmatter reference, troubleshooting, and screenshots: [obsidian export docs](https://ogham-mcp.dev/docs/obsidian-export/).
  455. </details>
  456. <details>
  457. <summary><b>Open Knowledge Format (portable round-trip bundles)</b></summary>
  458. Round-trip portability for your memories. Ogham reads and writes [Open Knowledge Format (OKF) v0.1](https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve-data-sharing), the markdown-based interchange format Google Cloud published in June 2026. The same bundle is portable to any other OKF-speaking tool -- Google's Knowledge Catalog, a colleague's homegrown reader, or your own future system.
  459. ```bash
  460. # Export your profile as an OKF v0.1 bundle directory
  461. ogham export --format okf
  462. # Round-trip it back (auto-detected as an OKF bundle)
  463. ogham import ogham-okf-<profile>-<timestamp>
  464. ```
  465. The bundle is a directory tree:
  466. ```text
  467. ogham-okf-<profile>-<timestamp>/
  468. ├── index.md # declares okf_version: "0.1" (+ ogham_graph_version: 1)
  469. ├── context.jsonld # predicate URIs, with Schema.org alignments where they fit
  470. ├── viewer.html # self-contained Cytoscape.js graph (opens with file://)
  471. ├── memories/
  472. │ ├── <slug>-<uuid8>.md # one markdown file per memory
  473. │ └── ...
  474. └── entities/ # present only if the profile has a typed-edge graph
  475. ├── <slug>-e<entity_id>.md # one file per entity, edges as frontmatter triples
  476. └── ...
  477. ```
  478. Each memory file has YAML frontmatter (`type`, `id`, `tags`, `timestamp`, `source`, optional `title`) and the memory body as markdown. `type:` is derived from the first `type:X` tag alphabetically (falling back to `Memory`). Round-trip preserves UUID, content, tags, source, and any extension metadata; the embedding is regenerated on import.
  479. The `viewer.html` is a 425 KB self-contained file with [Cytoscape.js](https://github.com/cytoscape/cytoscape.js) (MIT) vendored inline -- no server, no internet, no CDN. Open it in any browser via `file://` to see your memories as a graph coloured by type, with edges following intra-bundle markdown links. Pass `include_viewer=false` to skip it.
  480. Import behaviour:
  481. - Memories with the `id:` extension upsert by UUID (idempotent re-imports).
  482. - Memories without `id:` insert as new; the count surfaces as `missing_id_count` in the result.
  483. - The importer requires a bundle-root `index.md` with `okf_version` declared so pointing it at a random directory fails fast.
  484. **Importing the entity graph** is opt-in and off by default:
  485. ```bash
  486. # See what it would do -- writes nothing
  487. ogham import <bundle> --with-graph --graph-dry-run
  488. # Actually import the entities/ layer
  489. ogham import <bundle> --with-graph
  490. ```
  491. The default is off because the `entities` table has no profile column -- it is
  492. global, scoped only through `memory_entities` and `entity_edges` -- so importing
  493. a graph touches rows every profile reads.
  494. Two things worth knowing before you run it:
  495. - **It merges, it does not restore.** Importing into a profile that already has
  496. a graph moves matching edges forward rather than returning the profile to the
  497. bundle's state. Into a fresh profile the result is exact.
  498. - **There is no undo, so there is a dry run.** Snapshotting the profile first
  499. does not give you one -- the snapshot is built from this same export path, and
  500. edge qualifiers do not round-trip through it. `--graph-dry-run` reports exactly
  501. what the real run would do: entities to create, edges to write, edges already
  502. present, and edges whose target is missing from the bundle.
  503. Re-running is safe. An edge that already exists is skipped rather than rewritten,
  504. so a retry after a partial failure converges instead of churning.
  505. Scope: this is for **your own bundles**. Importing a bundle from someone else's
  506. install is not supported -- the reader is bounded against corruption, not against
  507. a hostile bundle.
  508. User-facing write-up: [Ogham v0.15 speaks Open Knowledge Format](https://ogham-mcp.dev/blog/okf-round-trip-v015/).
  509. </details>
  510. <details>
  511. <summary><b>Importing existing memory (Claude Code, Claude.ai, JSON)</b></summary>
  512. ### From Claude Code (auto-memory MD files)
  513. Claude Code's auto-memory system writes per-project notes under `~/.claude/projects/<encoded-cwd>/memory/`. Each note is a markdown file with YAML frontmatter (`name`, `description`, `type`, optional `originSessionId`). Pull them into Ogham:
  514. ```bash
  515. ogham import-claude-code ~/.claude/projects/<encoded-cwd>/memory \
  516. --project ogham --dedup 0.8
  517. ```
  518. Each parseable file becomes one Ogham memory tagged `source:claude-code-memory + type:<frontmatter type> + project:<inferred or explicit>`. `MEMORY.md` (the index) and dotfiles are skipped. Files without recognisable frontmatter log a warning and are skipped.
  519. The encoded-cwd directory naming is lossy on hyphenated repo names: `openbrain-sharedmemory` decodes to `sharedmemory` because every `/` and `-` becomes the same separator. Pass `--project NAME` to override the inferred tag and keep your project tags consistent.
  520. The importer respects `inscribe_enabled()` -- `--no-inscribe` and `OGHAM_INSCRIBE_ENABLED=false` skip the import. Re-runs are dedup-safe via the `--dedup` cosine threshold (default 0.8). MCP tool: `import_claude_code_memories(directory, project_tag=...)`.
  521. ### From Claude.ai (conversation data export)
  522. Anthropic offers a first-party data export at **Settings → Privacy → Request your data**. After ~24-48h you receive a ZIP containing `conversations.json`. Pull it into Ogham:
  523. ```bash
  524. ogham import-claude-ai ~/Downloads/data-<id>-batch-0000 --profile claude-ai
  525. ```
  526. Accepts the ZIP itself, the unzipped directory, or `conversations.json` directly. Each `(human, assistant)` turn-pair becomes one memory with the assistant turn as content (the signal you'll search on) and the human prompt in `metadata.user_prompt` (recoverable for context). Tagging: `source:claude-ai`, `claude-conversation:<title-slug>`, optional `project:<tag>`.
  527. A conservative smart filter drops pleasantry exchanges; pass `--no-smart-filter` to keep them. Use `--since 2026-01-01` to import only recent conversations, or `--mode raw` for one memory per individual message instead of per turn-pair.
  528. To get an LLM-distilled summary of an imported conversation, call `compile_wiki(topic="claude-conversation:<slug>")` via MCP. Verbatim ingest plus on-demand synthesis means you keep the raw turns *and* get a digest, without the importer making LLM calls upfront. The summary regenerates whenever the source memories change.
  529. UUIDs from the export land in metadata so re-importing the same export later only adds new turns. MCP tool: `import_claude_ai_export(path, profile, mode=...)`.
  530. **Bulk imports skip per-memory enrichment** -- the Claude Code, Claude.ai, and JSON importers all write through `import_memories`, which embeds + dedups + inserts in batches but **skips per-memory entity extraction and auto-link** (a 600-memory import would otherwise run thousands of secondary RPCs). Imported memories are immediately searchable via embedding + keyword. To populate the entity graph after a bulk import, run `ogham backfill-entities --profile <name>` (see Entity graph below).
  531. ### From a JSON export
  532. ```bash
  533. ogham export --profile work > backup.json
  534. ogham import backup.json --profile work-restored
  535. ```
  536. Round-trips the full memory schema (content, embeddings, tags, metadata, lifecycle state). Useful for migrating between deployments or seeding a fresh profile from another.
  537. </details>
  538. <details>
  539. <summary><b>Entity graph + backfill</b></summary>
  540. Ogham extracts entity tags from every stored memory at ingest (people, files, errors, locations, projects -- pure regex, no LLM). v0.14 added the live wire-up so those tags also populate a separate entity graph used for spreading-activation retrieval and cross-memory connection suggestions.
  541. After applying migration 036 on an existing deployment, run a one-shot backfill to populate historical memories:
  542. ```bash
  543. ogham backfill-entities --profile work
  544. ```
  545. The backfill walks the memories table, runs the entity extractor, and links each memory to its entities via `link_memory_entities`. ON CONFLICT DO NOTHING makes re-runs free. New writes after v0.14 are linked automatically; the backfill only matters for memories created before the upgrade.
  546. Once the graph is populated:
  547. - `suggest_connections` returns memories that share entities with an anchor memory (was always empty before).
  548. - `entity_graph_density` returns real numbers (count of distinct entities and edges per profile).
  549. - The `spread_entity_activation_memories` RPC walks the bipartite memory/entity graph for context-rich retrieval.
  550. MCP tool: `backfill_entities(profile=None, batch_size=200)`.
  551. </details>
  552. <details>
  553. <summary><b>Scoring, condensing, and entity enrichment</b></summary>
  554. **Scoring and condensing** -- three server-side features run automatically, no configuration needed:
  555. - **Novelty detection.** When you store a memory, Ogham checks how similar it is to what you already have. Redundant content gets a lower novelty score and ranks quieter in search results. You can still find it, but it won't push out more useful memories.
  556. - **Content signal scoring.** Memories that mention decisions, errors, architecture, or contain code blocks get a higher signal score. A debug session where you fixed a real bug ranks above a casual note about a meeting. The scoring is pure regex, no LLM involved.
  557. - **Automatic condensing.** Old memories that nobody accesses gradually shrink. Full text becomes a summary of key sentences, then a one-line description with tags. The original is always preserved and can be restored if the memory becomes relevant again. Run `compress_old_memories` manually or on a schedule. High-importance and frequently-accessed memories resist condensing.
  558. **Entity enrichment** -- every memory is automatically enriched at ingest with structured entity tags, no LLM calls, pure regex and dictionary matching across 18 languages:
  559. - **Six entity categories.** Events (wedding, concert, meeting), activities (hiking, coding, cooking), emotions (frustrated, happy, relieved), relationships (sister, boss, colleague), quantities (3 books, 5 miles), and locations (Berlin, Tokyo -- via GeoNames database).
  560. - **18 languages.** English, German, French, Spanish, Italian, Portuguese, Brazilian Portuguese, Dutch, Polish, Russian, Ukrainian, Turkish, Arabic, Hindi, Japanese, Korean, Chinese, and Irish. Each language includes common inflected forms (case endings, verb tenses, lenition) so "svadʹbu" matches "svadʹba" in Russian and "bhainis" matches "bainis" in Irish.
  561. - **Timeline table.** Search results include a chronological timeline with pre-computed "days ago" and memory ID cross-references. Helps LLM readers answer temporal questions without doing date arithmetic.
  562. - **Lost in the Middle reordering.** Search results are reordered so the highest-relevance memories appear at the start and end of the context, where LLMs pay the most attention (Liu et al., 2023).
  563. </details>
  564. <details>
  565. <summary><b>Cross-encoder reranking (FlashRank) + ONNX local embeddings</b></summary>
  566. **Cross-encoder reranking** -- optional FlashRank cross-encoder reranking for self-hosters who want better ranking precision. Adds ~300ms per search on CPU. After Ogham's hybrid search returns candidates, FlashRank (ms-marco-MiniLM-L-12-v2, 21MB) rescores each result against the query using deeper token-level attention. The final score blends retrieval ranking with cross-encoder ranking.
  567. BEAM benchmark impact: R@10 0.69 → 0.70, MRR +8pp. Biggest gain: temporal reasoning 0.84 → 0.98. [Full results](https://ogham-mcp.dev/blog/flashrank-reranking/).
  568. ```bash
  569. pip install ogham-mcp[rerank]
  570. # or: uv add ogham-mcp[rerank]
  571. export RERANK_ENABLED=true
  572. export RERANK_ALPHA=0.55 # 55% cross-encoder, 45% retrieval score
  573. ```
  574. The model downloads on first use (~21MB). Self-hosters who want speed over precision leave it off (the default).
  575. **ONNX local embeddings** -- run BGE-M3 locally with ONNX Runtime, dense and sparse vectors in a single model pass, no API calls, no GPU required. Contributed by [@ninthhousestudios](https://github.com/ninthhousestudios). The ONNX provider produces 1024-dim dense vectors plus neural sparse vectors. When sparse vectors are available, Ogham automatically uses three-signal Reciprocal Rank Fusion (dense + FTS + sparse) instead of the default two-signal path.
  576. ```bash
  577. pip install ogham-mcp[onnx]
  578. # Download the model (~2.2GB)
  579. ogham download-model bge-m3
  580. export EMBEDDING_PROVIDER=onnx
  581. export EMBEDDING_DIM=1024
  582. ```
  583. Your database schema must use `vector(1024)` for the embedding column. Performance on CPU: ~0.3s per short text, ~10s for long documents (5K+ chars). RSS: ~4.3GB peak. The ONNX provider is designed for self-hosters who want zero API costs. Cloud users should use Gemini or Voyage for lower latency.
  584. </details>
  585. <details>
  586. <summary><b>Database setup, schema files, and upgrading</b></summary>
  587. Ogham works with Supabase or vanilla PostgreSQL. Run the schema file that matches your setup:
  588. | File | Use case |
  589. |------|----------|
  590. | `sql/schema.sql` | [Supabase](https://supabase.com) Cloud |
  591. | `sql/schema_selfhost_supabase.sql` | Self-hosted Supabase with RLS |
  592. | `sql/schema_postgres.sql` | Vanilla PostgreSQL / [Neon](https://neon.tech) (no RLS) |
  593. Supabase and Neon both include pgvector out of the box -- no extra setup needed. If you're self-hosting Postgres, you need PostgreSQL 15+ with the [pgvector](https://github.com/pgvector/pgvector) extension installed. We develop and test against PostgreSQL 17. For Postgres, set `DATABASE_BACKEND=postgres` and `DATABASE_URL=postgresql://...` in your environment.
  594. **Local pgvector test database** -- Postgres integration tests are intentionally scratch-only. They run real memory rows through PostgreSQL + pgvector, but skip unless `DATABASE_URL` contains `scratch` or `OGHAM_TEST_ALLOW_DESTRUCTIVE=1` is set. This keeps ordinary `pytest` runs from touching a personal or production Ogham database.
  595. ```bash
  596. make test-postgres-db
  597. export DATABASE_BACKEND=postgres
  598. export DATABASE_URL=postgresql://ogham:ogham@localhost:5433/ogham_scratch
  599. uv run pytest -m postgres_integration
  600. # or:
  601. make test-postgres
  602. ```
  603. The test harness applies the canonical `sql/schema_postgres.sql` to an empty scratch database, and reapplies the idempotent baseline migrations needed by current tests on older scratch databases. External Supabase + Ollama integration tests are opt-in:
  604. ```bash
  605. OGHAM_RUN_EXTERNAL_INTEGRATION=1 uv run pytest -m integration -v
  606. # or:
  607. make test-external
  608. ```
  609. ### Upgrading an existing Ogham database
  610. For v0.10.x → v0.11.0 (memory lifecycle release), see [UPGRADING.md](https://github.com/ogham-mcp/ogham-mcp/blob/main/UPGRADING.md). The short version:
  611. ```bash
  612. ./sql/upgrade.sh $DATABASE_URL # applies 025 + 026 + 027 idempotently
  613. ```
  614. Fresh installers do NOT need this -- `sql/schema.sql` already reflects the post-v0.11.0 state.
  615. For older versions (v0.4.x through v0.10.x), the same `upgrade.sh` script walks through every migration in order -- temporal columns, halfvec compression, sparse embeddings, RRF/BM25 search, then the v0.11.0 lifecycle additions. Each is idempotent.
  616. ```bash
  617. # Postgres / Neon (psql required)
  618. ./sql/upgrade.sh $DATABASE_URL
  619. # Supabase: paste migration files into the SQL Editor in order
  620. # (025_memory_lifecycle.sql → 026_memory_lifecycle_split.sql → 027_audit_log_backfill.sql
  621. # are the v0.11.0 set)
  622. ```
  623. Selected migration highlights:
  624. - **016** adds the `sparse_embedding` column for ONNX BGE-M3 sparse vectors.
  625. - **017** upgrades the search function to true Reciprocal Rank Fusion with length-normalised keyword scoring ([Cormack et al., 2009](https://doi.org/10.1145/1571941.1572114)).
  626. - **025 / 026** add the memory lifecycle table + triggers (see [UPGRADING.md](https://github.com/ogham-mcp/ogham-mcp/blob/main/UPGRADING.md)).
  627. - **027** backfills the `audit_log` table for installs that predate it.
  628. **Rollback scripts** live under `sql/migrations/rollback/` with a `DANGER_` prefix and require explicit session-variable opt-in before they do anything. See `sql/migrations/rollback/README.md`.
  629. All migrations are idempotent -- safe to re-run. The upgrade script checks your pgvector version and skips halfvec if pgvector is below 0.7.0. New installs don't need migrations -- the schema files already include everything.
  630. **Upgrading the CLI (uv tool)** -- uv caches aggressively. A plain `uv tool install ogham-mcp` after a new release may install the old version. Use `--refresh` to force a fresh resolve from PyPI:
  631. ```bash
  632. uv tool uninstall ogham-mcp
  633. uv cache clean
  634. uv tool install --refresh "ogham-mcp[gemini,postgres]"
  635. ```
  636. Verify with `ogham config` (shows version and provider at the top). If you still see the old version, nuke the tool environment directory and retry:
  637. ```bash
  638. rm -rf ~/.local/share/uv/tools/ogham-mcp
  639. uv tool install --refresh "ogham-mcp[gemini,postgres]"
  640. ```
  641. This is a [known uv caching behaviour](https://docs.astral.sh/uv/concepts/cache/) -- the resolver cache is separate from the package cache and survives `uv cache clean` without `--refresh`.
  642. </details>
  643. <details>
  644. <summary><b>Skills (ogham-research, ogham-recall, ogham-maintain)</b></summary>
  645. Ogham ships with three workflow skills in `skills/` that wire up common MCP tool chains. Install them in Claude Code, Cursor, or any client that supports skills.
  646. | Skill | Triggers on | What it does |
  647. |-------|-------------|-------------|
  648. | `ogham-research` | "remember this", "store this finding", "save what we learned" | Checks for duplicates via hybrid_search before storing. Auto-tags with a consistent scheme (`type:decision`, `type:gotcha`, etc.). Uses `store_decision` for architectural choices. |
  649. | `ogham-recall` | "what do I know about X", "find related", "context for this project" | Chains hybrid_search, find_related, and explore_knowledge to surface connections. Bootstraps session context at project start. |
  650. | `ogham-maintain` | "memory stats", "clean up my memory", "export my brain" | Runs health_check, get_stats, cleanup_expired, re_embed_all, link_unlinked. Warns before irreversible operations. |
  651. Skills call existing MCP tools -- they don't replace them. The MCP server must be connected for skills to work.
  652. ```bash
  653. npx skills add ogham-mcp/ogham-mcp # all three
  654. npx skills add ogham-mcp/ogham-mcp --skill ogham-recall # one
  655. cp -r skills/ogham-research skills/ogham-recall skills/ogham-maintain ~/.claude/skills/ # manual
  656. ```
  657. </details>
  658. ## Documentation
  659. Full docs and integration guides at [ogham-mcp.dev](https://ogham-mcp.dev).
  660. ## Credits
  661. Inspired by [Nate B Jones](https://www.youtube.com/watch?v=2JiMmye2ezg) and his work on persistent AI memory.
  662. Named after [Ogham](https://en.wikipedia.org/wiki/Ogham), the ancient Irish alphabet carved into stone -- the original persistent memory.
  663. ## License
  664. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.