CogniRepo

CogniRepo

mcp-name: io.github.ashlesh-t/cognirepo

Persistent memory and context for any AI tool. Not a chatbot — infrastructure.

[CI] [Security] [PyPI version] [GitHub Stars] [License: MIT] [Python 3.11+] [Discord]

[alt text]

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 (< 10K LOC), native file reads are fast enough that the MCP tool schema overhead (~3,700 tokens for 36 tools) takes more than you save. Break-even is roughly 4 tool calls on a medium-sized repo.

CogniRepo vs. claude-context / similar tools:

Conclusion: prefer CogniRepo when you value institutional memory across sessions. Use simpler tools when you just need one-shot code retrieval on a small codebase.

Why it helps — measured numbers

Benchmarked across 6 real open-source repos (FastAPI, Flask, Celery, Ansible, Moby/Docker, Kubernetes) using 30 structured prompts tested against Claude, Gemini, and Cursor/Codex.

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.

Measured 2026-09-17. Lookup latency < 0.1 ms on all repos. "Targeted" is the realistic baseline (grep + read top-2 matching files, approximating what an agent would actually do); "naive" reads every matching file in full and is an upper bound, not a realistic comparison. moby and kubernetes are indexable (Go support confirmed, COGNIREPO-500) but not yet in this table — hours of indexing, scheduled separately. Full numbers and methodology, including precision@k, symbol hit rate, and memory recall: docs/METRICS.md.

Run cognirepo benchmark on your own codebase to reproduce. See docs/METRICS.md.

How it works

[alt text]

Quick start

Requirements

• Python 3.11+
• API key (optional — only needed for cognirepo ask): ANTHROPIC_API_KEY, GEMINI_API_KEY, OPENAI_API_KEY, or GROK_API_KEY. Indexing, memory, summarization, and all MCP tools work fully offline.

Install

Recommended — pipx (global, one command, works on all distros)

pipx install cognirepo

That's it. cognirepo setup handles the rest — it installs optional extras (languages, security, providers) via pipx inject automatically when you enable them in the wizard.

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)

# Arch Linuxsudo pacman -S python-pipx
# Debian / Ubuntusudo apt install pipx
# macOSbrew install pipx
# Any platform (fallback)pip install pipx --user

Inside a virtual environment (alternative)

python -m venv .venv && source .venv/bin/activatepip install cognirepo# extras are installed by the setup wizard automatically

Development install (from source)

pipx install -e '.[dev,security,languages]'# or inside a venv: pip install -e '.[dev,security,languages]'

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

# One-command onboarding (init + index + auto-configure MCP for Claude/Cursor/VS Code):cognirepo setup
# Or step by step:cognirepo init --no-index     # scaffold .cognirepo/cognirepo index-repo .        # index your codebase (required before MCP tools work)cognirepo index-repo . --daemon  # index and run watcher in background
# Keep the index fresh after every commit (indexes just the changed files, in the background):cognirepo install-hooks
# Check everything is working:cognirepo status                        # shows symbol count, graph nodes, signal warmthcognirepo doctor                        # full health check (exit 0 healthy / 1 warnings / 2 errors)cognirepo doctor --resources            # where memory and disk go: processes, store sizes, leftovers
# Query through multi-model orchestrator:cognirepo ask "why is auth slow?"
# Manage background watchers (one per repo, however many sessions run):cognirepo watch --ensure-running        # start it if it is not runningcognirepo list                          # show all running watcher daemonscognirepo list -n <PID> --view          # tail the log of a specific watchercognirepo list -n <PID> --stop          # stop a watcher

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-<project>:

{  "mcpServers": {    "cognirepo-myproject": {      "command": "cognirepo",      "args": ["serve", "--project-dir", "/abs/path/to/myproject"],      "env": {}    }  }}

The --project-dir flag locks the MCP server to that project's .cognirepo/ directory. When Claude has multiple projects open simultaneously, each connector reads only its own memories — never mixing data across projects or teams.

Cursor / Copilot

cognirepo export-speccp adapters/cursor_mcp_config.json .cursor/mcp.json# Restart Cursor — CogniRepo tools appear in the tool selector

Docker

cp .env.example .env          # add your API keysdocker compose up mcp         # MCP stdio server

MCP Tools — complete reference

All 36 tools are available to Claude, Cursor, and any MCP-compatible client.

Core retrieval

User & session intelligence

Error tracking & prevention

Session start

Memory & storage

Reporting

Grounded pushback

Cross-repo (organization)

Knowledge graph — what gets indexed

The knowledge graph is significantly richer than a simple call graph.

Node types

Edge types

IMPORTS and INHERITS edges are built automatically during index-repo from Python AST. Use subgraph("MyClass", depth=2) or dependency_graph("mymodule") to query them.

User behavior profiling

CogniRepo tracks how you interact across sessions and builds a profile that Claude uses to calibrate its responses — without you having to repeat preferences every session.

What gets tracked

• Depth preference — inferred from average query length: concise / medium / detailed
• Question types — distribution across: why, what, how, fix, explain, where, refactor, add
• Domain vocabulary — top terms that appear frequently in your queries
• Code focus — percentage of queries referencing code identifiers (symbols, functions)
• Sample queries — last 3 queries for Claude to infer framing style

Accessing your profile

# MCP tool (Claude calls automatically at session start):get_user_profile()
# CLI:cognirepo user-prefs

Example profile output

{  "depth_preference": "detailed",  "top_question_type": "how",  "question_type_distribution": {"how": 12, "why": 8, "fix": 5},  "top_terminology": ["auth", "token", "session", "middleware", "validate"],  "code_focus_percent": 73,  "framing_hints": "prefers detailed responses; often asks 'how' questions; domain vocabulary: auth, token, session",  "total_queries_tracked": 47}

Claude receives framing_hints at session start and adjusts response length, code density, and terminology accordingly. The profile accumulates over time — more accurate the more you use it.

Error tracking & prevention

CogniRepo logs every error that occurs during sessions — whether it's a Python exception, a failed build step, or a tool call that went wrong. Errors are stored with:

• Dedup signature — prevents the same error from inflating the count
• Prevention hint — a targeted suggestion to avoid the same error class
• Occurrence context — last 5 occurrences with file path and error message
• Query context — the query or action that triggered the error

Logging errors

# MCP tool (Claude calls after errors):record_error("TypeError", "expected str got int", "config/parser.py", "fix config loading")

Viewing error patterns

# MCP tool:get_error_patterns()

Returns:

[  {    "error_type": "TypeError",    "count": 7,    "files": ["config/parser.py", "api/handlers.py"],    "last_seen": "2026-04-22T10:30:00Z",    "prevention_hint": "Wrong type — validate inputs at function boundary.",    "recent_context": "expected str got int in parse_config"  }]

Built-in prevention hints

Session history

Every cognirepo ask exchange is persisted to .cognirepo/sessions/. Sessions are indexed by UUID and retrievable via:

# List recent sessions:cognirepo sessions
# MCP tool — Claude calls at session start to resume context:get_session_history(limit=5)

Each entry returns: session ID, created timestamp, message count, model used, and the last user/assistant exchange for quick context scan.

Architectural summaries

cognirepo init automatically prompts to run cognirepo summarize after the first index. This produces a 3-level LLM summary of the entire codebase:

• Level 1 — repo-wide summary (what the project does, key modules, entry points)
• Level 2 — per-directory summaries (what each package is responsible for)
• Level 3 — per-file summaries (what each file contains, key functions/classes)

Summaries are stored in .cognirepo/index/summaries.json and served via the architecture_overview MCP tool — zero token cost for Claude to understand the big picture.

# Auto-prompted on first init. Run manually anytime:cognirepo summarize
# Fully local — no API key required. Reads from ast_index.json, runs in < 1 second.# File summaries are also embedded into FAISS for semantic architecture queries.

Repo insights

What CogniRepo can tell you about your repo: generate_insights() (or cognirepo insights) turns everything CogniRepo has recorded about a project — episodic events, architectural decisions, open challenges, branch/commit activity, index health — into one self-contained HTML report. Sourced only from real stored records; nothing fabricated. Screenshots below are from a real report generated on this repo (cognirepo insights --since 365d), not mockups:

[CogniRepo insights report, light mode] [CogniRepo insights report, dark mode]

cognirepo insights --since 90d   # writes .claude/insights/<repoName>-insights.html

Multi-model orchestration

cognirepo ask automatically picks the right model for each query:

cognirepo ask "where is verify_token defined?"       # → QUICK, answered locallycognirepo ask "why is auth slow?"                    # → EXPERT, Claude with full contextcognirepo ask --verbose "explain the circuit breaker"  # show tier/score/signals

Provider fallback chain: Grok → Gemini → Anthropic → OpenAI. All errors are logged to .cognirepo/errors/<date>.log — no raw tracebacks shown to users.

Language support

Full details and roadmap: docs/LANGUAGES.md

Storage layout

.cognirepo/  config.json              ← project settings (project_id, models, retrieval weights, indexing, behaviour bounds)  cognirepo.lock           ← cross-process store lock (OS advisory lock; never delete by hand)  graph/    graph.pkl              ← NetworkX DiGraph (optionally Fernet-encrypted)    graph.journal          ← append-only journal, present only while `index-repo` runs or after a failed save    behaviour.json         ← per-symbol hit counts, user profile, error patterns (bounded, see CONFIGURATION.md)  index/    ast_index.json         ← reverse symbol index + file records    ast.index              ← FAISS IndexIDMap2 for code symbols    ast_metadata.json      ← parallel metadata for ast.index rows    manifest.json          ← git SHA, platform info and checksums for integrity checks (`verify-index`)    summaries.json         ← LLM architectural summaries (Level 1–3)    last_indexed.json, endpoints.json, http_calls.json, …   ← indexing bookkeeping  vector_db/    chroma/                ← default semantic-memory store (ChromaDB); `semantic.index` when `vector_backend: "faiss"`  memory/    episodic.json          ← append-only event journal    semantic_metadata.json ← metadata for the local FAISS semantic store (`vector_backend: "faiss"`) and project memory  learnings/    learnings.json         ← structured learnings: decisions, bugs, prod issues  watchers/                ← watcher registry (<pid>.json), heartbeat, lease (watcher.writer), logs  sessions/                ← conversation session files  errors/                  ← daily error logs (full tracebacks, never shown to users)  hook.log, hook.last      ← output and last result of the git post-commit hook (`install-hooks`)

Files the loaders set aside are kept, never silently deleted: graph.pkl.corrupt-<ts> (may well hold an intact graph — see cognirepo graph restore), vector_db/chroma.corrupt-<ts>/, *.stale. cognirepo doctor --resources lists them with sizes. Expected sizes and tuning knobs: docs/RESOURCES.md.

Everything under .cognirepo/ is .gitignored by default — never committed. Fernet encryption is opt-in at storage.encrypt: true in config.json; it covers the graph, behaviour model, org graph, episodic log and local FAISS store, but not the AST index or the default Chroma store — see SECURITY.md for exactly what is and isn't covered.

CLI reference

# Setupcognirepo init                  # scaffold + configure; auto-indexes + auto-summarizescognirepo setup-env             # interactive API key wizardcognirepo test-connection       # test API key connectivitycognirepo migrate-config        # migrate deprecated config keys
# Indexingcognirepo index-repo [path]     # AST-index a codebasecognirepo summarize             # generate LLM architectural summaries (auto-prompted on init)cognirepo seed --from-git       # seed behaviour weights from git historycognirepo verify-index          # verify AST index integritycognirepo coverage              # per-directory symbol counts
# Queryingcognirepo ask <query>           # route through multi-model orchestratorcognirepo retrieve-memory <q>   # similarity searchcognirepo search-docs <q>       # full-text search in .md filescognirepo log-episode <event>   # append episodic eventcognirepo history               # print recent episodic eventscognirepo sessions              # list recent conversation sessions
# Memory managementcognirepo store-memory <text>   # save a semantic memorycognirepo user-prefs            # view/set global user preferencescognirepo prune [--dry-run]     # prune low-score memories
# Health & monitoringcognirepo prime                 # generate session bootstrap briefcognirepo status                # live retrieval signal weights + index healthcognirepo doctor [--fix]        # full health check; --fix auto-repairs common issuescognirepo doctor --resources    # processes, store sizes and left-over files (read-only)cognirepo benchmark             # run quantitative value benchmarkscognirepo install-hooks         # git post-commit hook: reindex changed files after each commitcognirepo graph restore         # list quarantined graphs and restore the best intact one (dry-run; --apply)
# Organizationcognirepo org create <name>     # create local organizationcognirepo org link <org> [path] # link repo to organizationcognirepo org list              # list organizations
# Daemon managementcognirepo list                  # list MCP servers, running daemons (`-n PID --stop` to stop one)cognirepo watch --ensure-running  # start the background file-watcher (one per repo); `--status` to inspect

Every command, flag and exit code: docs/CLI_REFERENCE.md.

Future Plans

Priorities drawn from the v0.3.0 benchmark findings and community feedback. Now at v2.5.0 — some items below have since landed; each is annotated where that's the case.

Near-term

• Go call-graph indexing — done (COGNIREPO-203): Go receiver-qualified method calls (recv.Method()) now resolve through who_calls/CALLS edges — tree-sitter's Go selector_expression names its method field field, not property (the JS convention the extractor previously assumed), so method calls were silently dropped; fixed in _ts_collect_calls (intelligence/indexer/ast_indexer.py). A second bug in the same function — a call-collection recursion depth cap of 12, too shallow for a Go method wrapping an if-statement around a composite-literal call argument — was also raised (to 60). Go IMPORTS edges from go.mod-resolved local package imports are implemented (_extract_imports_go/_resolve_go_import_to_file). Live-verified against cognirepo_test_repo/advanced/moby: 4/4 hand-verified callers resolved (100%, vs. the 90% target) after both fixes.
• cognirepo ask — done: multi-model orchestrator (QUICK/STANDARD/COMPLEX/EXPERT tiers) is implemented and wired as a real CLI command (_cmd_ask_local, interface/cli/main.py). Streaming REPL mode (see Longer-term) is not yet built.
• Incremental re-index on save — done: the file-watcher daemon (cognirepo watch) debounces writes (config.json → indexing.debounce_ms, default 500ms) and batches indexer/graph saves; tests/test_watcher_debounce.py covers this including flush-on-shutdown.
• CLAUDE.md mandatory-call relaxation — benchmark feedback (Moby tests) flagged that forcing context_pack before every file read adds latency under memory pressure. A --fast mode that skips the tool-first gate for files under 50 lines is not yet implemented.

Medium-term

• Platform (planned for 3.0) — a single per-user daemon, a local control API (/api/v1) with a cognirepo ui command, and an SQLite (WAL) graph store to replace the resident in-memory graph. The Engram console that consumes the API lives in its own repository. Local-only by design: no hosted relay, no remote access. Tracked in the "Platform" epic.
• Kubernetes / 2M-LOC scale validation — K8-1 through K8-5 test suite not yet completed. Goal: full scheduling-decision trace at < 8 000 tokens with CogniRepo vs. > 50 000 without.
• Plugin-registry pattern detection — done (COGNIREPO-203): a static, annotation-only heuristic pass tags symbols reachable via dynamic dispatch — celery-style @task/ @shared_task decorators, register(...)-style plugin-registration calls, Python __init_subclass__ hooks, and packaging entry-points (pyproject.toml [project.entry-points.*] / setup.cfg [options.entry_points]) — with dispatch:"dynamic" plus a RELATES_TO edge to a dynamic_dispatch CONCEPT node (_detect_dynamic_dispatch, _apply_entry_points_dispatch in intelligence/indexer/ast_indexer.py). Annotation-only by design — never fabricates a CALLS edge. Live-verified against cognirepo_test_repo/medium/celery's real @shared_task functions.
• BM25 over symbol names — partially done: core/_bm25.py is used by intelligence/retrieval/hybrid.py as the circuit-breaker fallback ranker (and by episodic search) when embeddings are unavailable, but it isn't yet the primary ranking signal for symbol-name partial-match recall (e.g. HttpClient matching http_client) in the normal (embeddings-available) retrieval path.
• Cross-session memory warm-up — Ansible benchmark noted episodic/memory retrieval is low-value on fresh sessions. cognirepo prime exists but is not run automatically on init; will make it opt-in default.

Longer-term

• cognirepo ask streaming REPL — full interactive session with tier routing, session persistence, and sub-agent delegation.
• Similarity edges in knowledge graph — done (COGNIREPO-202): post-index FAISS k-NN pass over already-embedded FUNCTION/CLASS symbol vectors adds a SIMILAR_TO edge (cosine ≥ 0.80, max 5/node, cross-file only) between near-duplicate symbols, both directions. Gated via config.json → indexing.similarity_edges (default on below 20k candidate symbols). Weighted (discounted) into intelligence/retrieval/hybrid.py::_graph_score.
• VS Code / JetBrains extension — surface lookup_symbol, context_pack, and who_calls directly in the editor sidebar without requiring an MCP-capable host.

Documentation

Community

Questions, feedback, or just want to see what others are building? Join the CogniRepo Discord.

Want to contribute? See CONTRIBUTING.md — issues labeled good first issue are scoped for a first PR.

License

CogniRepo is licensed under the MIT License.

• Free to use, study, modify, and distribute
• Use in proprietary products and commercial services — no restrictions
• No requirement to open-source your application

See LICENSE for full details.