kodara 0.2.1

Memory Layer for AI Development — Architecture-aware context engine

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

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

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