cogvault

[Get started](#get-started-in-30-seconds) · [Why](#why) · [Compared](#compared-to) · [How it works](#how-it-works) · [Benchmark](#benchmark) · [Install](#install) · [Quickstart](#quickstart) · [MCP](#as-an-mcp-server-claude-code-cursor-any-mcp-client) · [Fleets](#multi-tenant-fleets)

Get started in 30 seconds

Claude Code plugin — MCP server plus a skill that tells the agent when to recall and when to record:

/plugin install cogvault --marketplace NBibikov/cogvault

Claude Code before 2.1.275: /plugin marketplace add NBibikov/cogvault, then /plugin install cogvault@cogvault.

Memory lives in ~/.cogvault/memory (set COGVAULT_TENANT to change it). The plugin adds /cogvault:remember.

Any MCP client, one line (needs uv):

claude mcp add cogvault -- uvx cogvault mcp --tenant ~/agent/memory

Claude Desktop, Cursor, Windsurf, Cline — JSON config

Add to claude_desktop_config.json, ~/.cursor/mcp.json, or your client's MCP config:

{

"mcpServers": { "cogvault": { "command": "uvx", "args": ["cogvault", "mcp", "--tenant", "~/agent/memory"] } } }

Already have Markdown memory? Point the tenant at it — nothing to import. Claude Code's auto-memory works as-is (frontmatter type, [[links]] and all):

M=~/.claude/projects/<project>/memory

uvx cogvault index --tenant $M --ignore MEMORY.md # first pass embeds, later passes are incremental uvx cogvault search --tenant $M "how do we deploy"

The MCP server indexes on start by itself; the CLI search reads the existing index. --ignore MEMORY.md keeps the index file from competing with the cards it points to.

Unedited answers from a real session (Sonnet, plugin installed, a demo memory of six cards); only the waiting time is cut.

Why

Most "AI agent memory" tools want to be an autonomous LLM daemon that summarizes your work into an opaque database or a graph you can't read. For a fleet of coding agents that just need to *reliably recall a decision, a bug fix, or an infra detail*, that's the wrong trade.

cogvault makes the opposite bet:

• Your Markdown files are the source of truth. Open them, edit them, git diff them. The SQLite index is a derived cache — delete it and it rebuilds from the files.
• One library, many tenants. Each agent gets an isolated memory namespace via its own directory. A process loads each embedding model once and shares it across every tenant it touches; with the stdio MCP server that means one small process per agent session, not a central daemon.
• No LLM in the loop. Ingest and retrieval are deterministic. Your agent *is* the LLM — it doesn't need a second one to remember.
• Local, private, offline. FastEmbed runs on-device. Nothing leaves your machine.

Compared to

Checked against each project's README and docs on 2026-10-05.

Pick something else when: you want an LLM to distil and merge facts for you (mem0), relationships between entities are the point (Graphiti), you want the agent to manage its own memory (Letta), or you want a richer notes app around the same Markdown idea, with Obsidian sync and a hosted option (basic-memory — the closest to cogvault).

Pick cogvault when: you run several agents and want each one's memory isolated in its own directory behind one process; you want recall to be deterministic and offline; and you want to *measure* it — cogvault eval scores recall on your agents' real queries and cogvault analyze lists what they tried to recall and couldn't.

How it works

Anatomy of a recall

Hybrid retrieval fuses semantic (vector) and keyword (BM25/FTS5) ranking with Reciprocal Rank Fusion, then applies optional temporal decay (recent memory outranks stale) and MMR (diverse top results, not five near-duplicates). Each card contributes only its best chunk, so one long file can't fill the whole result list.

Benchmark

Measured on real recall traffic, not synthetic questions: 66 queries sampled from the query logs of 6 live agent tenants (58% Ukrainian, the rest English), each judged against the actual cards — including answers that no configuration returned. One query has no answer in memory and counts as a gap, so 65 are scored. Every configuration was re-indexed from scratch on copies of the same tenants with cogvault 0.11.0.

What the numbers do and don't say:

• hit@1 is a tie. All four land within 0.54–0.57, and the 95% bootstrap intervals overlap almost completely. Real agent queries read like card titles, so the right card usually wins on its name alone.
• The gap is in the top 5. e5-small with the summary chunk puts the answer in the top 5 for 91% of queries vs. 80% for the default MiniLM and 77% for English-only bge on this mixed-language memory. That's what an agent reading 5 results actually feels.
• 65 queries is still a small sample. Treat differences under ~0.1 as noise. The aggregate numbers are in assets/benchmark.json; the queries are private and stay in each tenant.

Reranking

A cross-encoder reads the query and each candidate card together, so it can tell which card answers the question, not only which one is about the same topic. With rerank = "BAAI/bge-reranker-v2-m3-int8", cogvault scores the hybrid top 10 by the first 800 characters of each card file and reorders them. On the same 65 queries (cogvault 0.12.0, e5-small + summary chunk):

The reranker made 17 queries better and 3 worse. The 95% bootstrap interval of the hit@1 gain is +0.09 to +0.34. The cost is ~2 GB RAM and 1–2 s per recall on an Apple M-series CPU, so it runs only in the shared daemon and in cogvault eval (--no-rerank scores without it).

Run the same check on your own memory: put judged queries in /.cogvault-golden.jsonl ({"query": "...", "relevant": ["file.md"]}, empty relevant = a known gap) and run cogvault eval --tenant DIR.

Choosing an embedding model

Agent memory is often not English-only. The default is multilingual so nothing is *broken* out of the box — but pick the model that matches your fleet's language mix (set COGVAULT_MODEL, or Config(model=...)). Switching models auto-rebuilds the index.

*From the benchmark above: 65 real queries over mixed EN/UK memory, cogvault 0.11.0. On English-only memory bge-small-en is a fine choice; on Ukrainian content it returns a negative relevance margin (a distractor outranks the answer), so it is unsafe for non-English memory. Run cogvault eval on your own vault to decide.

COGVAULT_MODEL=BAAI/bge-small-en-v1.5 cogvault index --tenant ~/agent/memory

Pin the model per tenant so it travels with the data instead of relying on every command exporting COGVAULT_MODEL (forget it once and a model mismatch silently re-embeds the whole index). Drop