karna-ai

---

Self-Evolving Context

Karna learns from how agents use it and gets better over time — with zero human labels.

Feature	What it does
Session Tracking	Records every tool call, entity served, and file modified
Gap Signals	Computes 6 implicit quality metrics (context utilization, file prediction accuracy, follow-up rate, token efficiency, tool selection efficiency, intelligence per token)
Relevance Learning	Discovers which entities are useful for which queries and boosts them in future searches
Self-Optimization	Identifies the weakest quality dimension and proposes (or applies) improvements

karna sessions .    # View session quality signals
karna optimize .    # Run the self-improvement loop

Session tracking is on by default (local-only, no data leaves your machine). Opt out with --no-session-tracking or KARNA_SESSION_TRACKING=0.

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

Add to .cursor/mcp.json:

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

Add to .mcp.json:

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

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     |
                                                                                       v
                                                                              Session Tracking
                                                                                       |
                                                                              Gap Signal Extraction
                                                                                       |
                                                                           ┌───────────┴───────────┐
                                                                           v                       v
                                                                   Relevance Learner      Self-Optimizer
                                                                   (boost table)          (autoresearch)

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 + session tracking)
karna live [path]            # Start Live View only
karna status [path]          # Show graph stats
karna query [path] "topic"   # Search from terminal
karna sessions [path]        # View session data and quality signals
karna optimize [path]        # Run self-improvement loop (--apply to execute)

Options for serve:

karna serve . --no-session-tracking   # Disable session tracking
karna serve . --no-live-view          # Disable 3D visualization

Research Papers

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

Paper 2: Self-Evolving Context Layers: Implicit Learning from Agent Behavior in Code Knowledge Graphs Shailesh Tripathi, 2026. (Forthcoming)

@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   # 118 tests, all green

We welcome contributions. See CONTRIBUTING.md for guidelines.

License

Apache License 2.0. See LICENSE.

---

---

Support

Questions or issues? We're here to help:

• Issues: https://github.com/shaileshai/karna-ai/issues
• Discussions: https://github.com/shaileshai/karna-ai/discussions

---

Made with ❤️ by Shailesh