# Kodara

**Memory Layer for AI Development**

Kodara converts your codebase into structured, queryable memory — so your AI assistant always has the right context, not the entire repository.

```
Without Kodara:  AI reads 44 files  →  41,160 tokens  →  $0.62/query
With Kodara:     AI reads 2 files   →   2,400 tokens  →  $0.04/query
                                                      ↑ 94% reduction
```

---

## The Problem

Every time you ask your AI assistant a question, it reads the entire codebase.
No memory. No architecture awareness. Just raw file loading.

- Wastes tokens on irrelevant files
- Loses architectural context between sessions
- Breaks existing patterns by not knowing what already exists
- Costs multiply fast at team scale

## The Solution

Kodara sits between your codebase and your AI.
It indexes the project once, builds a dependency graph, and on every query returns only the relevant modules — with their relationships, summaries, and key symbols.

Your AI gets surgical context instead of a firehose.

---

## Quick Start

```bash
pip install kodara

cd your-project
kodara init          # index project + build memory
kodara ask "How does authentication work?"
```

No API keys. No configuration. Works with any AI tool.

---

## Commands

### Core

| Command | What it does |
|---------|-------------|
| `kodara init` | Scan project, build dependency graph, create `.kodara/` memory |
| `kodara ask "<query>"` | Query project memory, get relevant context |
| `kodara context` | Generate `ARCHITECTURE.md` for your AI assistant |

### Architectural Intelligence

| Command | What it does |
|---------|-------------|
| `kodara impact <file>` | Which modules break if you change this file? |
| `kodara onboard` | Generate reading guide for new developers |
| `kodara review` | Analyze uncommitted changes + impact before committing |
| `kodara diff <base>` | Impact analysis vs a branch or commit |

### Memory & History

| Command | What it does |
|---------|-------------|
| `kodara history <file>` | Git evolution of a file (commits, authors, change frequency) |
| `kodara note add <file> "<text>"` | Annotate a file with WHY-layer context |
| `kodara note list` | Show all developer annotations |
| `kodara snapshot` | Save current project memory state |
| `kodara snapshot list` | List all snapshots |
| `kodara snapshot diff <date>` | Compare current vs snapshot (what changed?) |

### Tracking

| Command | What it does |
|---------|-------------|
| `kodara stats` | Token savings and cost reduction report |
| `kodara status` | Current index status and health |
| `kodara watch` | Live auto-update as files change |

### API & Export

| Command | What it does |
|---------|-------------|
| `kodara serve` | FastAPI server on `http://127.0.0.1:8742` |
| `kodara graph` | Export dependency graph (JSON / DOT / Mermaid) |

---

## Real Performance Numbers

Tested on a 44-file Python project (Kodara itself):

| Query | Without | With Kodara | Reduction |
|-------|---------|-------------|-----------|
| "How does the context engine work?" | 41,160 tok | 2,378 tok | **94.2%** |
| "Where is semantic search?" | 41,160 tok | 2,776 tok | **93.3%** |
| "How are stats tracked?" | 41,160 tok | 1,138 tok | **97.2%** |
| "How does git history work?" | 41,160 tok | 1,713 tok | **95.8%** |
| "How does impact analysis work?" | 41,160 tok | 4,291 tok | **89.6%** |

**Average: 94% token reduction**

_Methodology: "without" = full codebase read. "with" = module metadata + 2 most relevant files._
_Pricing: $15/1M tokens (GPT-4o / Claude Opus input)._

### Cost at Scale

| Usage | Per developer/month | Per developer/year |
|-------|--------------------|--------------------|
| Light (20 queries/day) | save **$255** | save **$3,065** |
| Medium (50 queries/day) | save **$638** | save **$7,663** |
| Heavy (100 queries/day) | save **$1,277** | save **$15,326** |

| Team size | Monthly savings | Annual savings |
|-----------|----------------|----------------|
| 5 devs | $3,192 | $38,314 |
| 10 devs | $6,385 | $76,628 |
| 50 devs | $31,928 | $383,138 |

---

## How It Works

```
kodara init
    │
    ├── Scans all source files (Python, JS/TS, Go, Rust, Java, C/C++, Ruby, PHP)
    ├── Extracts: classes, functions, imports, exports via AST
    ├── Builds dependency graph (NetworkX DiGraph)
    ├── Generates semantic summaries per module
    ├── Collects git history (commit frequency, authors, change hotspots)
    └── Saves to .kodara/index.json (project-local, git-ignorable)

kodara ask "How does X work?"
    │
    ├── Tokenizes + stems query
    ├── IDF-weighted keyword scoring across all modules
    ├── Graph expansion: pulls in direct dependencies
    ├── Returns: top N modules + their relationships
    └── Surfaces any developer notes (kodara note) for those files
```

### Storage

Everything lives in `.kodara/` inside your project:

```
.kodara/
  index.json       # module graph + summaries
  stats.json       # token savings history
  notes.json       # developer annotations
  snapshots/       # periodic memory captures
    2024-01-15_143022.json
```

Add `.kodara/` to `.gitignore` or commit it — your choice.

---

## Architecture

```
kodara/
  indexer/         — AST scanner, 8+ languages, import extraction
  graph/           — NetworkX DiGraph, BFS traversal, hub detection
  memory/          — JSON storage, atomic writes, index versioning
  search/          — SemanticScorer: stemming + IDF + optional cosine similarity
  context_engine/  — Query → relevant modules + graph expansion
  git/             — Git history collection (one-pass, subprocess)
  impact/          — BFS through reverse dependency graph, risk levels
  onboard/         — Layer assignment (entry/core/foundation/utility), reading order
  stats/           — Token savings tracker, cost calculation
  diff/            — Changed files → impact analysis
  notes/           — Developer annotations (WHY layer)
  snapshots/       — Periodic index captures + comparison
  summarizer/      — Heuristic summaries (+ optional Anthropic Haiku)
  architecture/    — Graph export: JSON, Graphviz DOT, Mermaid
  api/             — FastAPI: POST /index, POST /query, GET /graph
  cli/             — Click CLI entry point
```

---

## Installation

```bash
# Minimal (no AI summaries)
pip install kodara

# With Anthropic summaries (optional — better module descriptions)
pip install "kodara[anthropic]"

# With numpy cosine similarity (optional — better semantic search)
pip install "kodara[semantic]"

# Everything
pip install "kodara[all]"
```

Requires Python 3.10+.

---

## Example Output

```
$ kodara ask "How does payment processing work?"

Context for: "How does payment processing work?"
Found 6 relevant modules (1,840 tokens)

  billing/processor.py      ★★★★★  PaymentProcessor, process_charge()
  billing/stripe_client.py  ★★★★   StripeClient, create_intent()
  billing/models.py         ★★★    Payment, Refund, Invoice
  api/billing_routes.py     ★★★    POST /pay, POST /refund
  config/payments.py        ★★     Stripe keys, retry config
  utils/currency.py         ★★     format_amount(), convert()

  Dependency chain: api/billing_routes → billing/processor → billing/stripe_client

$ kodara impact billing/processor.py

Impact Analysis: billing/processor.py
Risk: HIGH

  Direct (2):   api/billing_routes.py, workers/charge_worker.py
  Indirect (4): api/webhooks.py, reports/revenue.py, ...

$ kodara stats

Token savings — all time
  Queries: 47   Tokens saved: 1,823,040   Money saved: $27.35
```

---

## License

MIT for personal and open-source use.
Commercial license required for team deployments — see [getkodara.dev](https://getkodara.dev).
