Skip to content
MCP server

cogvault

Local, offline memory for AI agents built on plain Markdown with hybrid search

Runs locallyStatus and history
Install
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 cogvault

Add to claude_desktop_config.json

{
  "mcpServers": {
    "cogvault": {
      "command": "uvx",
      "args": [
        "cogvault"
      ]
    }
  }
}
Install in CursorOpens Cursor, which asks you to confirm. Or add it by hand:

Add to ~/.cursor/mcp.json

{
  "mcpServers": {
    "cogvault": {
      "command": "uvx",
      "args": [
        "cogvault"
      ]
    }
  }
}
Install in VS CodeOpens VS Code, which asks you to confirm. Or add it by hand:

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 default
  • COGVAULT_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

  1. Codebase Memory

    MCP server

    Local MCP server that builds a code knowledge graph for AI coding agents

    Runs locally
    • Open source
    • 48.7K GitHub stars
    • Knowledge and memory
  2. XERJ

    MCP server

    Local search engine for AI agents with cited answers over your code and docs

    Runs locally
    • Open source
    • 19.2K GitHub stars
    • Knowledge and memory
  3. MCP 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
  4. Local-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
  5. note1

    MCP server

    MCP server giving AI assistants search and summaries across your note1 meetings

    • 4 tools
    • Remote
    • Free trial
    • 1 GitHub star
    • Productivity