CogniRepo

What CogniRepo MCP server does

CogniRepo MCP server gives AI coding tools a persistent local context layer for software repositories. It combines several representations of a codebase: an AST-based symbol index, a NetworkX knowledge graph, FAISS vector search, BM25 retrieval, episodic events, and stored conversation context. These stores support both code navigation and project memory rather than only returning matching files.

The system can retain architecture notes, decisions, errors and prevention hints, user preferences, and previous session exchanges. It also builds a local summary hierarchy from files to directories to the repository and makes those summaries available for semantic search. Shared state lets different connected AI tools use the same accumulated project knowledge.

How it works

Initialize a repository, create its local CogniRepo data, and run an index before connecting MCP clients. The index records symbols, imports, inheritance, calls, files, and concepts. Symbol lookup uses the reverse index for fast file-and-line results, while semantic and lexical searches retrieve broader context. A background watcher can keep the index updated after the initial scan.

The architecture is local and CPU-oriented by default. Embeddings use fastembed and ONNX without requiring PyTorch or CUDA. Architectural summaries are generated from the local AST index, so that operation does not require an external model API. The project also describes an optional orchestration path that classifies query complexity, assembles context, and routes requests to models such as Claude or Gemini Flash; provider credentials are relevant to that workflow, not to indexing or the MCP tools themselves.

Setup and configuration

Python 3.11 or newer is required. The recommended installation is:

pipx install cognirepo

A virtual environment installation is also documented with pip install cognirepo. Run cognirepo setup for onboarding, including initialization, indexing, and automatic MCP configuration for supported local clients. For manual setup, use cognirepo init --no-index, then cognirepo index-repo .. The --daemon option starts a background watcher during indexing.

Use cognirepo status to inspect symbol and graph counts, and cognirepo doctor for a health check. Optional provider keys include ANTHROPIC_API_KEY, GEMINI_API_KEY, OPENAI_API_KEY, and GROK_API_KEY; they are needed only for cognirepo ask. No credentials are required for repository indexing, memory features, or MCP access.

Tools and capabilities

The MCP interface covers capabilities including:

• Fast symbol-to-file-and-line lookup
• Semantic retrieval over code, summaries, notes, and decisions
• Graph queries for imports, inheritance, calls, and repository relationships
• Persistent session and episodic event storage
• Error recording with prevention guidance
• User behavior profile retrieval
• Architectural decision recording
• Cross-tool context handoff through shared local state

CogniRepo MCP server is most appropriate for repositories around 15,000 lines of code or larger. On smaller projects, native file reads may be faster because the MCP schema itself adds context overhead.

Limitations and notes

Results are strongest on Python projects with relatively clear static structure. Dynamic dispatch, plugin registries, deep asynchronous patterns, Ansible variable precedence, and incomplete Go grammar support can reduce retrieval confidence. The project states that it reports uncertainty instead of fabricating call chains.

The reported token savings and lookup timings come from the project's benchmarks and vary by repository and task. Complex dynamic codebases show smaller gains than straightforward Python repositories. CogniRepo MCP server is offline for indexing and MCP operations, but optional model-based commands can require a user's provider API key. The repository is released under the MIT license.