cogni

Cogni

Open-core MCP (Model Context Protocol) server that drops into AI coding agents (Claude Code, Cursor, Windsurf, OpenCode) and reduces token consumption by giving them structured recall over a repository.

AI coding agents waste a large share of their token budget orienting in unfamiliar repos: re-reading files, grepping for symbols, and accumulating stale context. Cogni indexes a Python repository into a local SQLite code graph and exposes scoped MCP tools so agents move from overview to file to symbol to source instead of brute-forcing context.

Benchmark results

Measured on the httpx codebase using Claude Code SDK with n=5 runs per condition:

Methodology, fixed inputs, and reproduction steps are versioned in BENCHMARK.md. Raw report: bench-report.md.

Install

Homebrew (macOS, Linux)

brew tap islamborghini/tap
brew install islamborghini/tap/cogni
cogni --version

Go

go install github.com/islamborghini/cogni/cmd/cogni@latest

Requires Go 1.26+ and a working CGO toolchain (tree-sitter and SQLite are linked natively).

From source

git clone https://github.com/islamborghini/cogni
cd cogni
go build -o cogni ./cmd/cogni

Quickstart

Index a Python repo:

cd path/to/your/python/repo
cogni index . --stats

Run the MCP server (auto-indexes on startup, watches for file changes):

cogni serve --root /absolute/path/to/your/python/repo

cogni serve speaks JSON-RPC over stdio.

Using with Claude Code

Run cogni install once in the repository you want Claude Code to use Cogni in:

cd path/to/your/repo
cogni install

This does three things automatically:

1. Registers the Cogni MCP server in ~/.claude.json (use --local to write .mcp.json instead).
2. Writes a CLAUDE.md into the repo root telling Claude Code to prefer Cogni's tools over Read/Grep/Glob. This file is what actually changes agent behavior.
3. Indexes the repository.

Then restart Claude Code. Safe to re-run if anything changes.

Manual setup

If you prefer to configure things by hand:

MCP config (~/.claude.json or per-project .mcp.json):

{
  "mcpServers": {
    "cogni": {
      "command": "cogni",
      "args": ["serve", "--root", "/absolute/path/to/repo"]
    }
  }
}

CLAUDE.md in the repo root:

# Repository tooling

This repository has the **cogni** MCP server registered with these tools:

- `mcp__cogni__repo_overview`: high-level package map. Call FIRST for any architecture / "how does X work" question.
- `mcp__cogni__file_outline`: list symbols in a file without returning source. Use INSTEAD OF Read when you only need to know what a file exposes.
- `mcp__cogni__symbol_search`: find where a symbol is defined. Use INSTEAD OF Grep for definition lookups.
- `mcp__cogni__symbol_source`: return one symbol's body. Use INSTEAD OF Read after symbol_search.
- `mcp__cogni__find_references`: find usages of a symbol. Use INSTEAD OF Grep when answering "where is X used".

For code exploration tasks, **prefer the cogni tools** over Glob / Grep / Read. They return structured, scoped results and use 5-10x fewer tokens for the same answer.

Tools

Cogni exposes five MCP tools:

The index is local-only. Per-repo SQLite databases live under ~/.cogni/<repo-hash>/index.db.

Commands

cogni install [--root PATH] [--local]      # configure Claude Code + index (run once per repo)
cogni serve [--root PATH] [--db PATH]      # MCP server over stdio
cogni index [PATH] [--stats] [--db PATH]   # build or refresh the index
cogni bench [--runs N] [--mcp-config PATH] # run the token-savings benchmark
cogni --version                            # print version

How it works

1. Parse: tree-sitter (Python grammar, CGO-bound) extracts modules, classes, functions, methods, and their line ranges.
2. Store: symbols, files, and references are written to a per-repo SQLite database.
3. Serve: the MCP server exposes scoped queries over stdio so an agent can ask repo_overview instead of running ls -R, or symbol_source instead of reading a 600-line file.

Source layout:

cmd/cogni/         CLI entrypoint (serve, index, bench)
internal/parse/    tree-sitter Python parser
internal/index/    indexer + filesystem watcher
internal/store/    SQLite schema and queries
internal/mcp/      MCP tool definitions and handlers
internal/bench/    benchmark harness, scorers, task definitions

Contributing

Contributions are welcome. The project uses standard Go tooling and a small set of conventions.

Development setup

git clone https://github.com/islamborghini/cogni
cd cogni
go build -o cogni ./cmd/cogni
go test ./...

CGO is required (tree-sitter, SQLite). On macOS you need Xcode command line tools; on Linux a working gcc and libc headers.

Before opening a PR

gofmt -w .
go vet ./...
go test ./...
go build -o ./cogni ./cmd/cogni

CI runs fmt + vet + test on Ubuntu and macOS, plus golangci-lint. Both must be green.

Conventions

• Branches: feat/, fix/, chore/, test/, or docs/ prefix.
• PR titles: same prefix as the branch, conventional-commit style.
• Commits: small, frequent, one-sentence conventional-commit messages.
• Code: comments only when the why isn't obvious; identifiers should explain the what.

Where to start

• Open issues labeled good first issue or help wanted.
• New benchmark tasks in internal/bench/tasks.yaml. They must come from real merged PRs with checkable ground truth (see BENCHMARK.md).
• Bug reports with a minimal reproducer are very welcome.

License

Apache 2.0