karna 0.1.0

Self-healing identity graph for AI agents. Know your code before your agent reads a single line.

Karna

Your codebase, as a knowledge graph. For AI agents that don't waste tokens.

     

pip install karna && karna serve .

One command. Your AI agent now understands your entire codebase.

---

The Problem

Every time an AI coding agent starts a task, it reads files from scratch. Each file-read stays in the conversation history and gets retransmitted on every subsequent turn. We call this the Conversation History Tax -- and it grows quadratically with turn count.

An 8-turn coding session doesn't cost 8x a single turn. It costs 36x.

The result? You're burning tokens (and money) on context the agent already saw.

The Solution

Karna builds a persistent knowledge graph of your codebase -- every class, function, method, import, call, test, and contributor -- indexed and queryable in sub-second time. Instead of reading files turn after turn, your agent calls one tool and gets everything it needs.

Without Karna Turn 1: list_directory → 2,100 tokens Turn 2: grep_search → 3,400 tokens Turn 3: read_file → 4,200 tokens Turn 4: read_file → 3,800 tokens Turn 5: read_file → 2,900 tokens Turn 6: read_file → 1,800 tokens Turn 7: grep_search → 1,200 tokens Turn 8: final answer → 1,400 tokens ──────────────────────────── Total input: ~20,800 tokens

With Karna Turn 1: karna_task_context → 8,700 tokens Turn 2: final answer → done ──────────────────────────── Total input: ~8,700 tokens 58% saved.

Proven Results

This isn't a benchmark game. We ran a real agent A/B study -- Claude Sonnet 4, live API calls, actual coding tasks on a 1,125-file production codebase (FastAPI).

Task	Baseline	Karna	Savings
Add rate limiting middleware	17,243	8,613	50.0%
Fix WebSocket authentication bug	21,950	9,077	58.6%
Refactor dependency injection	17,096	8,013	53.1%
Add response caching layer	17,188	8,623	49.8%
Improve OpenAPI generation	30,274	9,403	68.9%
Mean	20,750	8,746	57.9%

Paired t-test: t(4) = 5.18, p < 0.007, Cohen's d = 2.96 (large effect). Full methodology and statistical analysis in the paper.

Works With Every MCP-Compatible Editor

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "karna": {
      "command": "karna",
      "args": ["serve", "--no-live-view", "."]
    }
  }
}

Claude Code

Add to .mcp.json:

{
  "mcpServers": {
    "karna": {
      "type": "stdio",
      "command": "karna",
      "args": ["serve", "--no-live-view", "."]
    }
  }
}

Gemini CLI

Add to settings.json:

{
  "mcpServers": {
    "karna": {
      "command": "karna",
      "args": ["serve", "--no-live-view", "."]
    }
  }
}

What Karna Extracts

Karna parses your code into a richly-connected graph:

Layer	What it captures
Entities	Classes, functions, methods, modules, files, tests, configs, packages, contributors
Relationships	contains, imports, calls, defines, inherits, tested_by, owned_by, co_changed
Call graphs	Intra-file function-to-function call edges
Body previews	First 10 lines of every function, class, and method
Git history	Authorship, file ownership, co-change patterns
Entity resolution	Automatically discovers implicit links -- test-to-implementation, cross-module dependencies

Validated on 1,556 source files across three repositories with zero parse errors:

Repository	Language	Files	Entities	Relationships
FastAPI	Python	1,125	6,488	8,200
Zod	TypeScript	391	1,431	2,911
Karna	Python	40	446	1,198

MCP Tools

The star tool is karna_task_context -- complete context in one call, one turn, minimal tokens.

Tool	What it does
karna_task_context(task)	One-shot context: entities, files to modify, tests, relationships, body previews
karna_understand(topic)	Lightweight overview of matching entities
karna_plan(task)	Planning mode: files to modify, tests to update
karna_context_for(role, task)	Role-specific context (implementer, test writer, reviewer)
karna_files_to_edit(task)	Targeted file list with line ranges
karna_read_entity(name)	Full entity detail with call graph and relationships
karna_changed(file)	Incremental re-parse after edits
karna_status()	Graph statistics
karna_who(file)	File ownership and connections

Architecture

Source Code ──> Parsers ──> Entity Resolution ──> SQLite + FTS5 ──> MCP Server ──> AI Agents
                  |               |                    |                |
                  |-- Python AST  |-- Blocking         |-- Entities     |-- Cursor
                  |-- TypeScript  |-- Scoring (6 dim)  |-- Relationships|-- Claude Code
                  |-- Git History |-- Union-Find        |-- FTS5 Index  |-- Gemini CLI
                  |-- Filesystem                                        |-- Any MCP client

Live View

Karna ships with a real-time 3D visualization of your knowledge graph (shown in the hero image above). Watch your codebase as a living, breathing graph -- with entity types color-coded, relationships traced, and agent activity highlighted live.

karna live .
# Open http://localhost:3849

CLI Reference

karna init [path]            # Build the knowledge graph
karna serve [path]           # Start MCP server (+ Live View)
karna live [path]            # Start Live View only
karna status [path]          # Show graph stats
karna query [path] "topic"   # Search from terminal

Research Paper

Karna: Reducing LLM Coding Agent Token Consumption by 58% via Persistent Code Knowledge Graphs Shailesh Tripathi, 2026. Read on Zenodo

@article{tripathi2026karna,
  title   = {Karna: Reducing LLM Coding Agent Token Consumption
             by 58\% via Persistent Code Knowledge Graphs},
  author  = {Tripathi, Shailesh},
  journal = {Zenodo preprint, DOI: 10.5281/zenodo.19433427},
  year    = {2026}
}

Contributing

git clone https://github.com/shailesht003/karna-ai
cd karna
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest   # 89 tests, all green

We welcome contributions. See CONTRIBUTING.md for guidelines.

License

Apache License 2.0. See LICENSE.

---

_{Built by Shailesh Tripathi · Production-grade cloud version with universal language support at karna.ai}