Cogvault

What cogvault MCP server does

The cogvault MCP server turns directories of Markdown files into searchable memory for AI agents. The Markdown files remain the source of truth; SQLite stores derived search data and can be rebuilt from those files. Each tenant is represented by its own directory, allowing multiple agents or projects to keep their memory namespaces separate.

It is designed for local and offline use. FastEmbed runs the embedding model on the host, while the retrieval process uses the local index. No additional LLM is used to ingest or recall information. Existing Markdown memory can be indexed in place, including Claude Code memory files with frontmatter and wiki-style links.

How it works

When the MCP process starts, it indexes the configured tenant directory. Subsequent indexing is incremental. A query combines semantic vector search with keyword search through BM25/FTS5, then merges the rankings with Reciprocal Rank Fusion. Optional temporal decay can favor newer memories, and maximal marginal relevance reduces duplicate results. Only the strongest matching chunk from each card is returned, preventing a single long file from filling the result set.

The same memory can be accessed through the MCP server or command-line interface. The repository also provides evaluation and analysis commands for measuring recall against agent queries and reviewing unsuccessful retrieval attempts. These features are useful when tuning memory for real workloads rather than relying only on synthetic tests.

Setup and configuration

The cogvault MCP server requires Python 3.10 or newer. With uv installed, an MCP client can launch it with a command such as:

uvx cogvault mcp --tenant ~/agent/memory

Claude Code can register the same command with claude mcp add. Claude Desktop, Cursor, Windsurf, and Cline can use an MCP JSON configuration containing uvx as the command and cogvault mcp --tenant ... as its arguments.

By default, the Claude Code plugin uses ~/.cogvault/memory. Set COGVAULT_TENANT to change that location for the plugin, or pass a tenant directory explicitly with --tenant. A pre-existing Markdown directory does not need an import step. The CLI can index it directly, and an ignore option can exclude files such as MEMORY.md when that file only points to other cards.

Tools and capabilities

The cogvault MCP server supports agent memory recall and recording through its MCP integration. Its command-line interface provides indexing and search, including commands such as cogvault index and cogvault search. The repository also exposes cogvault eval for recall scoring and cogvault analyze for examining retrieval behavior.

The Claude Code plugin adds a /cogvault:remember command and includes agent guidance for deciding when to recall or save information. The underlying storage remains readable Markdown, while the SQLite database acts as a replaceable cache.

Limitations and notes

Retrieval quality depends on the selected embedding model, chunking configuration, and the contents of the tenant’s files. The published benchmark describes results from a specific version and sample of real agent queries, so those figures should not be treated as a guarantee for another corpus.

This project is intended for deterministic local retrieval, not automatic LLM-based fact extraction or graph-based entity relationships. Choose another system if memory must be autonomously distilled by an LLM, organized around an entity graph, or managed as a hosted notes application. Each stdio MCP session runs as its own process; tenants are isolated by directory rather than by a central service.