
cogvault
Local, offline memory for AI agents built on plain Markdown with hybrid search
- Pricing
- Open source
- Platforms
- CLI, self-hosted, macOS
- Runs
- Locally
- Version
- 0.12.2
- Listing updated
- 1 day ago
About cogvault
cogvault is an open-source MCP server for knowledge and memory. It runs locally on your machine and is started by your AI client.
Your Markdown files stay the source of truth. Cogvault builds a SQLite index over them that can be deleted and rebuilt, so memory can be opened, edited and diffed in git. No LLM is involved in storing or recalling: retrieval fuses vector and keyword (BM25) ranking, with optional temporal decay and diversity re-ranking, and embeddings run on-device with FastEmbed.
Each agent gets an isolated namespace through its own directory, called a tenant, and a single process shares loaded embedding models across tenants. Existing Markdown memory, including Claude Code's auto-memory, can be indexed in place with no import. Commands such as eval and analyze score recall against your own judged queries and list what agents tried to recall but could not find.
The README's benchmark on 65 real queries from six agent tenants reports hit@5 of 0.91 with its best embedding setup, and a cross-encoder reranker lifting hit@1 from 0.60 to 0.80 at a cost of about 2 GB RAM and 1 to 2 seconds per recall. The README flags the sample as small.
Install
Run in a terminal
claude mcp add cogvault -- uvx cogvaultAdd to claude_desktop_config.json
{
"mcpServers": {
"cogvault": {
"command": "uvx",
"args": [
"cogvault"
]
}
}
}Add to ~/.cursor/mcp.json
{
"mcpServers": {
"cogvault": {
"command": "uvx",
"args": [
"cogvault"
]
}
}
}Add to .vscode/mcp.json
{
"servers": {
"cogvault": {
"type": "stdio",
"command": "uvx",
"args": [
"cogvault"
]
}
}
}Add to ~/.codeium/windsurf/mcp_config.json
{
"mcpServers": {
"cogvault": {
"command": "uvx",
"args": [
"cogvault"
]
}
}
}Add to your client's MCP settings (most use this shape)
{
"mcpServers": {
"cogvault": {
"command": "uvx",
"args": [
"cogvault"
]
}
}
}Configuration
COGVAULT_MODELEmbedding model override; otherwise .cogvault.toml in the tenant, then the multilingual defaultCOGVAULT_LOGRecall log: 'off' to disable, or a path to relocate the JSONL log
What it does
- Markdown source of truth
- Files stay editable; the index is a rebuildable cache.
- Hybrid retrieval
- Vector plus BM25 fused with reciprocal rank fusion.
- Multi-tenant isolation
- One directory per agent, one process.
- Fully offline
- On-device embeddings; nothing leaves the machine.
- Recall evaluation
- eval and analyze measure real recall quality.
- Optional reranker
- Cross-encoder reranking in the shared daemon.
- Claude Code plugin
- Bundles the server and a recall/record skill.
Good for
- Give a coding agent persistent decisions and bug fix notes
- Index existing Claude Code auto-memory without importing
- Keep separate memory for each agent in a fleet
- Check which queries an agent failed to recall
Pricing
Open source
Open source Python package
cogvault FAQ
Does it use an LLM?
No. Ingest and retrieval are deterministic; the agent itself is the LLM.
Does data leave my machine?
No. Embeddings run locally with FastEmbed.
How do I add it to Claude Code?
Install the plugin, or run claude mcp add cogvault -- uvx cogvault mcp --tenant <dir>.
Which languages does it handle?
The default embedding model is multilingual, and the benchmark mixes Ukrainian and English queries.
Is cogvault free?
Yes. cogvault is open source, so you can use and self-host it for free.
How do I add cogvault to Claude Code?
Run this command in your terminal: claude mcp add cogvault -- uvx cogvault
What are the best alternatives to cogvault?
The closest alternatives to cogvault are Codebase Memory, XERJ, Claude Code Ultimate Guide, Nautilus Compass Memory and note1.
Alternatives to cogvault

Codebase Memory
MCP serverLocal MCP server that builds a code knowledge graph for AI coding agents
Runs locally- Open source
- 48.7K GitHub stars
- Knowledge and memory

XERJ
MCP serverLocal search engine for AI agents with cited answers over your code and docs
Runs locally- Open source
- 19.2K GitHub stars
- Knowledge and memory

Claude Code Ultimate Guide
MCP serverMCP server for searching the Claude Code Ultimate Guide from any MCP client
Runs locally- Open source
- 6.5K GitHub stars
- AI models and LLM tooling

Nautilus Compass Memory
MCP serverLocal-first long-term memory layer for AI agents, served over MCP
Not checked yet- 5 tools
- Remote
- Open source
- 1.3K GitHub stars
- Knowledge and memory

note1
MCP serverMCP server giving AI assistants search and summaries across your note1 meetings
- 4 tools
- Remote
- Free trial
- 1 GitHub star
- Productivity
MedXpert 图书馆连接器(通用版)
MCP serverLocal MCP server that searches and answers questions over your own Markdown wiki
Runs locally- 4 tools
- Open source
- Knowledge and memory