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

---

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

After `kodara init` you'll see your token savings estimate immediately.

---

## Commands

> The differentiator between plans is project size and cloud infrastructure — not command availability on lower tiers.

### FREE — all users (up to 200 files)

| Command | What it does |
|---------|-------------|
| `kodara init` | Scan project, build dependency graph, create `.kodara/` memory |
| `kodara ask "<query>"` | Get relevant context for your AI assistant |
| `kodara status` | Current index status |
| `kodara watch` | Live auto-update as files change |
| `kodara stats` | Token savings and cost report |
| `kodara history <file>` | Git evolution: commits, authors, change frequency |
| `kodara note add <file> "<text>"` | Annotate a file with context |
| `kodara snapshot` | Save current project memory state |
| `kodara install-hook` | Git post-commit auto-update hook |
| `kodara repos list` | List all indexed projects |

### PRO — $19/month · everything in Free + unlimited files + cloud

| Command | What it does |
|---------|-------------|
| `kodara impact <file>` | Which modules break if you change this file? |
| `kodara context` | Generate `ARCHITECTURE.md` |
| `kodara review` | Analyze uncommitted changes + impact |
| `kodara diff <base>` | Impact analysis vs a branch or commit |
| `kodara why <file>` | WHY this file exists (git + notes + AI explanation) |
| `kodara simulate-change <file>` | Risk score + downstream cost + AI narrative |
| `kodara heatmap` | Responsibility heatmap |
| `kodara dna` | Architectural fingerprint — detect patterns |
| `kodara learn` | Save DNA snapshot |
| `kodara evolve` | DNA history over time |
| `kodara compare <p1> <p2>` | Compare two project architectures |
| `kodara drift` | Detect architectural drift since last snapshot |
| `kodara clone-pattern <url> --into <dir>` | Clone architectural structure from any repo |
| `kodara scan <url>` | Scan any GitHub repo |
| `kodara mcp` | MCP server — Cursor/Claude get context automatically |
| `kodara backup` | Upload `.kodara/` to cloud |
| `kodara restore` | Download backup |
| `kodara login` | Authenticate with email OTP |

### TEAM — $25/user/month · everything in Pro + shared memory

| Command | What it does |
|---------|-------------|
| `kodara onboard` | Reading guide for new developers |
| `kodara bus-factor` | Files only one person knows — single point of failure |
| `kodara debt` | Technical debt heatmap |
| `kodara arch-init` | Auto-detect architecture layers |
| `kodara check-architecture` | Validate layer rules, show violations |
| `kodara team cloud-create <name>` | Create shared team memory |
| `kodara team cloud-join <code>` | Join team with invite code |
| `kodara team cloud-push` | Sync memory to team |
| `kodara team cloud-pull` | Pull team memory |

### ENTERPRISE — custom annual contract · everything in Team

| Command | What it does |
|---------|-------------|
| `kodara ci-check` | Exit 1 on violations — for CI/CD pipelines |
| `kodara init-ci` | Create `.github/workflows/kodara.yml` |

Plus: SSO/SAML, on-premise deployment, SLA, dedicated support.

---

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

---

## Installation

```bash
# Free (no API keys needed)
pip install kodara

# With AI explanations for why/simulate-change (uses GitHub Models)
pip install "kodara[llm]"   # set GITHUB_TOKEN env var

# Pro features (MCP server, cloud backup, team memory)
pip install "kodara[pro]"

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

Requires Python 3.10+. Works on macOS, Linux, Windows.

---

## Plans

### Free — $0 forever
All core commands. Up to 200 files per project. Local storage only.
```bash
pip install kodara
```

### Pro — $19/month
Unlimited project size. Full analysis suite. Cloud backup. MCP integration.
Saves $147–$295/month on average. ROI from day one.
```bash
pip install "kodara[pro]"
```

### Team — $25/user/month
Everything in Pro. Shared memory — one developer indexes once, whole team benefits.
10 devs → saves $6,385/month on AI tokens. Coming soon at [getkodara.dev](https://getkodara.dev).

### Enterprise — Custom
Everything in Team. SSO/SAML, on-premise deployment, SLA, dedicated support.
Contact us at [getkodara.dev](https://getkodara.dev).

---

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

---

## 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 use (Pro/Team/Enterprise) — see [getkodara.dev](https://getkodara.dev).
