Purpose CogniRepo is local cognitive infrastructure for AI coding agents, used to provide persistent memory and context for any AI tool and reduce token usage. It is not a chatbot, but an intermediate layer between the codebase and AI tools. Every AI conversation starts from zero by default; Claude, Cursor, and Gemini do not remember what was fixed yesterday, which files are related to which features, or what decisions were made in the last sprint. CogniRepo is used to solve this problem.
Main capabilities
- Semantic memory: FAISS vector storage combined with sentence-transformer embeddings, capable of storing decisions, documents, and architecture notes, and retrieving them with natural language.
- Event log: an append-only event log, making it possible to understand what happened before a certain error.
- Knowledge graph: NetworkX DiGraph, connecting functions, classes, files, imports, inheritance chains, call relationships, and concepts, all queryable.
- AST reverse index: O(1) symbol lookup across the entire codebase in supported languages.
- User behavior profile: tracks the user's prompting style, allowing Claude to adjust its response style without re-explaining preferences every session.
- Error tracking: records errors and prevention hints, helping Claude avoid repeating the same error across sessions.
- Session history: persists conversation exchanges, so any session can continue from where the last one ended.
- Architecture summary: automatically generated on first initialization, entirely based on the local AST index (no API key required), generating a three-level summary tree of file -> directory -> repository, and embedding it into FAISS for semantic search.
- Multi-model orchestration: classifies query complexity -> builds context -> routes to the appropriate model, for example Claude for deep reasoning and Gemini Flash for quick lookups, all done automatically. All AI tools connected to this infrastructure can obtain the same accumulated project knowledge, and memory persists across sessions, across tools, and across time.
How to use It is recommended to install with pipx to create an isolated virtual environment. On first use, you need to run cognirepo init and cognirepo index-repo . first; only after indexing is complete will MCP tools (context_pack, lookup_symbol, who_calls, etc.) return data. When running cognirepo init, if you choose to configure Claude, it will automatically write .claude/CLAUDE.md and .claude/settings.json. The --project-dir flag locks the MCP server to that project's .cognirepo/ directory; when multiple projects are open at the same time, each connector reads only its own memory and does not mix data across projects or teams. There are 36 MCP tools in total, available for Claude, Cursor, and any MCP-compatible client. By default, CPU embeddings are used (fastembed/ONNX, no PyTorch/CUDA required); GPU requires additional steps. Indexing, memory, summaries, and all MCP tools can be fully offline; only cognirepo ask requires an optional API key (ANTHROPIC_API_KEY, GEMINI_API_KEY, OPENAI_API_KEY, or GROK_API_KEY).
Use cases Best suited for scenarios with a codebase size of ≥ 15K LOC. Official benchmarks cover repositories such as Flask, FastAPI, Celery, and Ansible (5,900+ files), showing a reduction of about 30%–78% in token usage compared with a targeted grep+read baseline; on medium-sized repositories, the break-even point is about 4 tool calls. On small repositories (<10K LOC), native file reading is fast enough, and the schema overhead of the 36 MCP tools (about 3,700 tokens) may make it not worth it. It is suitable for scenarios that value cross-session institutional memory, while simple tools are better suited for one-off code retrieval on small codebases. Use cognirepo benchmark to reproduce this on your own codebase.
Limitations It is most valuable on Python repositories with clear static structure. Dynamic dispatch patterns (such as Celery beat, plugin registries), deep Go codebases, and Ansible's 22-level variable precedence chain reduce retrieval confidence; the tool reports uncertainty rather than fabricating call chains. Some platform capabilities (such as a single-user daemon, local control API /api/v1, cognirepo ui, SQLite (WAL) graph storage) are marked as planned for 3.0. Kubernetes / 2M-LOC scale validation has not yet been completed. The streaming REPL mode of cognirepo ask has not yet been built. CLAUDE.md forced invocation relaxation (--fast mode) has not yetbeen implemented. BM25 has not yet become the primary ranking signal in the normal (embeddings available) retrieval path for partial matching recall of symbol names. Cross-session memory warm-up cognirepo prime already exists, but it does not run automatically at init.
