ashlesh-t/cognirepo

mcp-name: io.github.ashlesh-t/cognirepo
> Persistent memory and context for any AI tool. Not a chatbot — infrastructure.
---
**lookup_symbol returns file:line very quickly — grep takes 2–8 seconds.** On Python repos ≥ 15K LOC, CogniRepo cuts AI coding agent token usage by **~30–78%** vs. a targeted grep+read baseline (up to 96–99% vs. reading every matching file naively) — benchmarked on Flask, FastAPI, Celery, and Ansible (5,900+ files). Works with Claude Code, Cursor, and Gemini CLI. **Fully offline. No API keys required for indexing or any of the 36 MCP tools.**
---
What it does
Every AI conversation starts from zero. Claude, Cursor, Gemini — none of them remember
what you fixed yesterday, which files relate to which features, or what decisions were made
last sprint. CogniRepo fixes that.
It sits between your codebase and any AI tool, providing:
- **Semantic memory** — FAISS vector store with sentence-transformer embeddings. Store
decisions, docs, architecture notes. Retrieve them with natural language.
- **Episodic log** — append-only event journal. Know what happened before that error.
- **Knowledge graph** — NetworkX DiGraph linking functions, classes, files, imports,
inheritance chains, call relationships, and concepts. All queryable.
- **AST reverse index** — O(1) symbol lookup across your entire codebase in any supported language.
- **User behavior profiling** — tracks how you prompt so Claude adapts its response
style without you having to re-explain preferences every session.
- **Error tracking** — records errors with prevention hints so Claude avoids
repeating the same mistake across sessions.
- **Session history** — persists conversation exchanges so any session can resume
where the last one ended.
- **Architectural summaries** — auto-generated on first init; built entirely from
the local AST index (no API key needed). File → directory → repo summary tree,
embedded into FAISS for semantic search.
- **Multi-model orchestration** — classify query complexity → build context → route to the
right model. Claude for deep reasoning, Gemini Flash for quick lookups. All automatic.
Every AI tool that connects gets the same accumulated project knowledge. Memory persists
across sessions, across tools, across time.
---
When to use CogniRepo
**Most effective on codebases ≥ 15K LOC.** On small repos ( **Honest limits:** CogniRepo adds the most value on Python repos with clear static structure.
> Dynamic dispatch patterns (Celery beat, plugin registries), deep Go codebases, and Ansible's
> 22-level variable precedence chains reduce retrieval confidence. The tool reports uncertainty
> rather than hallucinating call chains.
Measured: lookup latency and token reduction (4 external repos)
Indexed 4 real repos, measured with cognirepo index-repo + cognirepo benchmark --json on
v2.4.0+ (2026-09-17). CPU-only, no GPU.
| Repo | Files | Lookup latency | Token reduction (naive) | Token reduction (targeted) | context_relevance |
|------|-------|----------------|--------------------------|------------------------------|-------------------|
| flask | 92 | 0.002 ms | 97.3% | 29.5% | 80.5% |
| fastapi | 1,178 | 0.003 ms | 97.6% | 63.5% | 97.1% |
| celery | 444 | 0.003 ms | 99.7% | 77.7% | 100.0% |
| ansible | 4,196 | 0.008 ms | 96.1% | 28.6% | 56.6% |
Measured 2026-09-17. Lookup latency **Why pipx?** It creates an isolated venv for cognirepo automatically so fastembed
> and all deps install cleanly. The cognirepo command is then globally available in
> every directory — no per-repo venv needed.
>
> **Arch Linux / Debian 12+ / Ubuntu 24.04+:** Do NOT pip install into system Python.
> These distros enforce PEP 668 and block system-wide pip installs. Use pipx.
Install pipx first (if needed)
Inside a virtual environment (alternative)
Development install (from source)
> **Note:** CPU-only embeddings are the default (fastembed/ONNX, no PyTorch/CUDA required).
> For GPU: pipx inject cognirepo 'cognirepo[gpu]' then install torch separately.
Run
> **First-time setup:** cognirepo init + cognirepo index-repo . must complete before
> MCP tools (context_pack, lookup_symbol, who_calls, etc.) return data.
---
Connect your AI tools
Claude Code / Claude Desktop (recommended — project-scoped)
Run cognirepo init inside your project — it asks if you want to configure Claude and
automatically writes .claude/CLAUDE.md and .claude/settings.json with the correct
project-locked connector.
Each project gets its **own isolated connector** named cognirepo- :