cognirepo

# CogniRepo

mcp-name: io.github.ashlesh-t/cognirepo
> Persistent memory and context for any AI tool. Not a chatbot — infrastructure.

[![CI](https://github.com/ashlesh-t/cognirepo/actions/workflows/ci.yml/badge.svg)](https://github.com/ashlesh-t/cognirepo/actions/workflows/ci.yml)
[![Security](https://github.com/ashlesh-t/cognirepo/actions/workflows/security.yml/badge.svg)](https://github.com/ashlesh-t/cognirepo/actions/workflows/security.yml)
[![PyPI version](https://badge.fury.io/py/cognirepo.svg)](https://badge.fury.io/py/cognirepo)
[![GitHub Stars](https://img.shields.io/github/stars/ashlesh-t/cognirepo?style=social)](https://github.com/ashlesh-t/cognirepo/stargazers)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![Discord](https://img.shields.io/badge/Discord-CogniRepo-5865F2?logo=discord&logoColor=white)](https://discord.com/channels/1488386981917360289/1488387271190380636)

![alt text](cognirepo.png)

---

**`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 **50–80%** compared to raw file reads — benchmarked on Flask, FastAPI, Celery, and Ansible (1,800+ files). Works with Claude Code, Cursor, and Gemini CLI. **Fully offline. No API keys required for indexing or any of the 34 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 (~4,100 tokens for 34 tools) takes more
than you save. Break-even is roughly 4 tool calls on a medium-sized repo.

**CogniRepo vs. claude-context / similar tools:**

| Feature | CogniRepo | claude-context / similar |
|---------|-----------|--------------------------|
| Pure code retrieval | ✓ (FAISS + graph + AST) | ✓ Often faster on first use |
| Episodic memory (what happened last sprint) | ✓ Persistent BM25 + vector | ✗ |
| Cross-agent handoff (Claude → Gemini → Cursor) | ✓ `last_context.json` shared | ✗ |
| User behaviour profile (adapts depth/style) | ✓ `get_user_profile()` | ✗ |
| Error pattern avoidance (learns from past fails) | ✓ `record_error()` | ✗ |
| Architectural decision records | ✓ `record_decision()` | ✗ |
| Multi-repo org graph (microservices) | ✓ `CHILD_OF` / `CALLS_API` edges | ✗ |

**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.

| Metric | Value | Notes |
|--------|-------|-------|
| Token reduction — Python repos | **50–84%** | FastAPI FA-2: 12 000 → 2 500 · FA-4: 2 000 → 450 · FL-4: 8 000 → 1 250 |
| Token reduction — average (all tested) | **~60%** | Across FA/FL/CE/AN where both baselines were captured |
| Token reduction — complex dynamic codebases | **20–35%** | Celery CE-4/CE-5; deep async/dynamic-dispatch patterns reduce gains |
| Symbol lookup latency | **< 1 ms** | vs. `grep` at 2–8 s on large repos |
| Accuracy vs. baseline | **equal or better in 100% of tests** | No regression observed; FA-2 accuracy improved Moderate → High |
| Cross-agent context handoff | **✅ validated** | CE-4: Claude primed index, Gemini CLI consumed it — 35% token saving, same accuracy |
| Dynamic dispatch coverage | **honest gap** | CE-3 (APScheduler beat dispatch) returned NA for both; CogniRepo does not fabricate call chains |
| Go/multi-language coverage | **partial** | Moby MO-2 showed 67% savings; MO-3-5 / K8-* incomplete pending Go grammar improvements |

> **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: precision@k and index build time (4 external repos)

Indexed 4 real repos, measured with `cognirepo index-repo` + `context_pack` queries. CPU-only, no GPU.

| Repo | Files | Index time | Lookup latency | precision@3 |
|------|-------|-----------|----------------|-------------|
| flask | 83 | 12s | 0.011 ms | **100%** |
| fastapi | 1,122 | 34s | 0.005 ms | **89%** |
| celery | 416 | 44s | 0.025 ms | **100%** |
| ansible | 1,813 | 145s | 0.018 ms | **80%** |

All repos: symbol hit rate 5/5, lookup latency < 0.1ms. All quality gates pass. Full numbers: [docs/METRICS.md](docs/METRICS.md).

Run `cognirepo benchmark` on your own codebase to reproduce. See [docs/METRICS.md](docs/METRICS.md).

---

## How it works

![alt text](cognirepo-workflow.png)

---

## 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)

```bash
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)

```bash
# Arch Linux
sudo pacman -S python-pipx

# Debian / Ubuntu
sudo apt install pipx

# macOS
brew install pipx

# Any platform (fallback)
pip install pipx --user
```

#### Inside a virtual environment (alternative)

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

#### Development install (from source)

```bash
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

```bash
# 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

# Check everything is working:
cognirepo status                        # shows symbol count, graph nodes, signal warmth
cognirepo doctor                        # full health check

# Query through multi-model orchestrator:
cognirepo ask "why is auth slow?"

# Manage background watchers:
cognirepo list                          # show all running watcher daemons
cognirepo list -n <PID> --view          # tail the log of a specific watcher
cognirepo 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>`:

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

The `--project-dir` flag locks the MC