gannonh/kata-context

kata-context

Structural and semantic codebase intelligence with persistent memory for AI coding agents. Indexes TypeScript and Python repositories into a SQLite knowledge graph with optional vector embeddings, then exposes graph queries, semantic search, pattern search, fuzzy symbol lookup, and durable memory operations via CLI commands. Every memory mutation produces a git commit for audit trail.

When to Use

Use kata-context when you need to:

• Search by intent — "find the authentication handler", "where is rate limiting implemented?" (semantic search)
• Understand code structure — what symbols exist in a file, what calls what, what imports what
• Find dependents — "what will break if I change this function/class?"
• Trace dependencies — "what does this symbol depend on?"
• Search for patterns — grep for TODOs, error handling patterns, specific API calls
• Find symbols by name — fuzzy-match when you know part of a symbol or file name
• Check index health — see how many symbols/edges are indexed, when last indexed
• Remember decisions — persist project decisions, patterns, and learnings as durable memories
• Recall by meaning — semantically search stored memories by natural language query
• Forget memories — remove outdated or incorrect memories
• Consolidate — merge related memories into a single distilled entry

Prerequisites

• Node.js ≥ 20
• ripgrep (rg) — required for the grep command. Install via brew install ripgrep or your package manager. All other commands work without it.
• OPENAI_API_KEY — required for search (semantic search), recall (semantic memory recall), and for generating embeddings during index. Set in your environment.

Quick Start

# 1. Index the current project (includes semantic embeddings if OPENAI_API_KEY is set)
kata-context index .

# 2. Check what's indexed
kata-context status

# 3. Semantic search — find code by meaning
kata-context search "authentication handling"
kata-context search "error recovery patterns" --top-k 5

# 4. Query the graph
kata-context graph dependents UserService
kata-context graph dependencies AppService
kata-context graph symbols src/service.ts

# 5. Search code
kata-context grep "TODO|FIXME"
kata-context find "user service"

Always run index first — graph and search commands need an indexed database. Memory commands (remember, recall, forget, consolidate) work independently of the index — they store memories as markdown files in .kata/memory/.

Global Options

All commands support these flags:

| Flag | Description | |------|-------------| | --json | Output structured JSON (for programmatic parsing) | | --quiet | Minimal output — names/paths only, one per line | | --db <path> | Path to SQLite database (default: .kata/index/graph.db) |

When neither --json nor --quiet is set, output is human-readable with formatted tables and headers.

Commands

kata-context index [path]

Index a project directory into the knowledge graph. Parses all TypeScript and Python files, extracts symbols and cross-file relationships (imports, calls, inheritance), and stores them in SQLite.

Supports incremental indexing: after the first full index, subsequent runs only process files changed since the last indexed git commit. Use --full to force a complete re-index.

kata-context index .
kata-context index /path/to/project
kata-context index . --json
kata-context index . --full          # Force full re-index

Output (human):

Index Complete
──────────────
  Files indexed      : 42
  Symbols extracted   : 187
  Edges created       : 324
  Duration            : 1250ms
  Database            : .kata/index/graph.db

Output (JSON):

{
  "filesIndexed": 42,
  "symbolsExtracted": 187,
  "edgesCreated": 324,
  "duration": 1250,
  "errors": [],
  "dbPath": ".kata/index/graph.db"
}

Output (quiet): File count only (e.g., 42).

kata-context status

Show knowledge graph statistics — symbol count, edge count, file count, and last indexed git SHA.

kata-context status
kata-context status --json

Output (JSON):

{
  "symbols": 187,
  "edges": 324,
  "files": 42,
  "lastIndexedSha": "abc1234",
  "dbPath": ".kata/index/graph.db"
}

kata-context graph dependents <symbol>

Find all symbols that depend on the given symbol — everything that imports, calls, or references it.

kata-context graph dependents UserService
kata-context graph dependents createConfig --json

Output (human):

Dependents of createConfig
──────────────────────────
  Symbol       Kind      Relationship  File              Line
  BaseService  class     calls         src/service.ts    8
  run          function  calls         src/consumer.ts   7

Output (JSON):

{
  "symbol": { "name": "createConfig", "kind": "function", "file": "src/utils.ts", "line": 7 },
  "dependents": [
    { "name": "BaseService", "kind": "class", "relationship": "calls", "file": "src/service.ts", "line": 8 }
  ]
}

Output (quiet): Symbol names only, one per line.

kata-context graph dependencies <symbol>

Find all symbols that the given symbol depends on — everything it imports, calls, or references.

kata-context graph dependencies AppService
kata-context graph dependencies run --json

kata-context graph symbols <file>

List all symbols defined in a file with their kinds, line ranges, export status, and edge counts.

kata-context graph symbols src/service.ts
kata-context graph symbols src/types.ts --json

Output (human):

Symbols in src/service.ts
─────────────────────────
  Name          Kind       Lines   Exported  In  Out
  BaseService   class      6-16    yes       2   1
  AppService    class      19-42   yes       3   2

Output (JSON):

{
  "file": "src/service.ts",
  "symbols": [
    { "name": "BaseService", "kind": "class", "lineStart": 6, "lineEnd": 16, "exported": true, "incomingEdges": 2, "outgoingEdges": 1 }
  ]
}

kata-context grep <pattern>

Search code using ripgrep with structured output. Supports regex patterns.

kata-context grep "TODO|FIXME"
kata-context grep "import.*from" --glob "*.ts" --context 2
kata-context grep "class.*Service" --json --max-results 20

Options:

| Option | Description | |--------|-------------| | --glob <pattern> | File glob filter (repeatable) | | --context <n> | Context lines before and after each match | | --case-sensitive | Force case-sensitive search | | --max-results <n> | Maximum number of matches |

Output (JSON):

{
  "pattern": "TODO",
  "matches": [
    { "file": "src/service.ts", "line": 15, "column": 3, "matchText": "TODO", "lineContent": "  // TODO: add retry logic" }
  ],
  "totalMatches": 1
}

Output (quiet): file:line pairs, one per line.

Note: Requires rg (ripgrep) to be installed. If not found, the command exits with a helpful error message.

kata-context search <query>

Semantic search over indexed symbol embeddings. Embeds your natural-language query and finds the most similar symbols by vector distance. Requires OPENAI_API_KEY and a prior index run with semantic embeddings.

Use search when you know what you're looking for but not where it is — e.g., "authentication handling", "database connection pooling", "error retry logic". For exact pattern matching, use grep. For symbol name matching, use find.

kata-context search "authentication handling"
kata-context search "error recovery patterns" --top-k 5
kata-context search "database connection" --kind function --json
kata-context search "rate limiting" --quiet

Options:

| Option | Description | Default | |--------|-------------|---------| | --top-k <n> | Maximum number of results to return | 10 | | --kind <kind> | Filter results by symbol kind (function, class, method, interface, typeAlias, enum, module, variable) | all kinds |

Output (human):

Semantic Search: "authentication handling"
──────────────────────────────────────────
  Model          text-embedding-3-small
  Total vectors  187
  Results shown  3

  #  Score   Name               Kind      File                   Lines
  ─  ─────   ────               ────      ────                   ─────
  1  0.8734  authenticateUser   function  src/auth.ts            10-30
  2  0.7621  UserService        class     src/services/user.ts   5-80
  3  0.6543  handleLogin        function  src/routes/login.ts    15-45

Output (JSON):

{
  "query": "authentication handling",
  "results": [
    {
      "rank": 1,
      "score": 0.8734,
      "distance": 0.1449,
      "symbol": {
        "id": "abc123",
        "name": "authenticateUser",
        "kind": "function",
        "filePath": "src/auth.ts",
        "lineStart": 10,
        "lineEnd": 30,
        "signature": "function authenticateUser(token: string): Promise<User>",
        "summary": "Validates a JWT token and returns the authenticated user"
      }
    }
  ],
  "model": "text-embedding-3-small",
  "totalVectors": 187,
  "totalResults": 1
}

Output (quiet): filePath:lineStart pairs, one per line (e.g., src/auth.ts:10).

Error handling:

| Error | Cause | Fix | |-------|-------|-----| | SEMANTIC_SEARCH_EMPTY_INDEX | No semantic vectors indexed | Run kata-context index . with OPENAI_API_KEY set | | SEMANTIC_OPENAI_MISSING_KEY | OPENAI_API_KEY not set | Set the environment variable | | SEMANTIC_SEARCH_MODEL_MISMATCH | Config model differs from indexed model | Re-index with kata-context index . --full |

kata-context remember <content>

Store a persistent memory entry as a markdown file with YAML frontmatter in .kata/memory/. Each mutation produces a git commit for audit trail.

Use remember to persist decisions, patterns, learnings, and architecture notes that should survive across sessions. Prefer remember over ad-hoc notes — memories are searchable via recall.

kata-context remember "Always use snake_case for DB columns"
kata-context remember "Auth uses JWT with 1h expiry" --category decision --tags "auth,jwt"
kata-context remember "Retry with exponential backoff for API calls" --category pattern --source "src/api.ts"
kata-context remember "SQLite FTS5 requires rebuild after schema changes" --json

Options:

| Option | Description | Default | |--------|-------------|---------| | --category <cat> | Category: decision, pattern, learning, architecture, etc. | learning | | --tags <tags> | Comma-separated tags for filtering | (none) | | --source <refs> | Comma-separated source file references | (none) |

Output (JSON):

{
  "id": "a1b2c3d4",
  "category": "decision",
  "tags": ["auth", "jwt"],
  "createdAt": "2026-03-23T10:00:00.000Z",
  "sourceRefs": [],
  "content": "Auth uses JWT with 1h expiry"
}

Output (quiet): Memory ID only (e.g., a1b2c3d4).

kata-context recall <query>

Semantically search stored memories by natural language query. Embeds the query and finds nearest memory vectors by similarity. Requires OPENAI_API_KEY.

Use recall when you need to find previously stored decisions, patterns, or learnings — e.g., "what did we decide about auth?", "database patterns", "error handling approach".

kata-context recall "authentication decisions"
kata-context recall "database patterns" --top-k 3
kata-context recall "error handling" --category pattern --json

Options:

| Option | Description | Default | |--------|-------------|---------| | --top-k <n> | Number of results to return | 5 | | --category <cat> | Filter results by memory category | all categories |

Output (JSON):

{
  "query": "authentication decisions",
  "results": [
    {
      "rank": 1,
      "id": "a1b2c3d4",
      "similarity": 0.8734,
      "distance": 0.1449,
      "category": "decision",
      "tags": ["auth", "jwt"],
      "content": "Auth uses JWT with 1h expiry"
    }
  ],
  "totalResults": 1
}

Output (quiet): <id>: <truncated content> per line.

Error handling:

| Error | Cause | Fix | |-------|-------|-----| | MEMORY_RECALL_EMPTY | No memories stored | Use remember to store some memories first | | MEMORY_RECALL_MISSING_KEY | OPENAI_API_KEY not set | Set the environment variable |

kata-context forget <id>

Delete a memory entry by its ID.

kata-context forget a1b2c3d4
kata-context forget a1b2c3d4 --json

Output (JSON):

{ "id": "a1b2c3d4", "deleted": true }

kata-context consolidate <ids...>

Merge multiple related memories into a single distilled entry. The originals are deleted and a new consolidated memory is created. Requires at least 2 memory IDs.

kata-context consolidate a1b2c3d4 e5f6g7h8
kata-context consolidate a1b2c3d4 e5f6g7h8 i9j0k1l2 --json

Output (JSON):

{
  "id": "m3n4o5p6",
  "mergedCount": 2,
  "category": "learning",
  "tags": ["consolidated", "auth"],
  "content": "[decision] Auth uses JWT...\n\n[pattern] Retry with backoff..."
}

kata-context find <query>

Fuzzy search for symbols and files by name using FTS5 full-text search.

kata-context find "user service"
kata-context find "config" --kind interface
kata-context find "app" --limit 5 --json

Options:

| Option | Description | |--------|-------------| | --kind <kind> | Filter by symbol kind (function, class, interface, type, enum, method) | | --limit <n> | Maximum number of results |

Output (JSON):

{
  "query": "config",
  "results": [
    { "name": "Config", "kind": "interface", "file": "src/types.ts", "lineStart": 1, "lineEnd": 4, "exported": true }
  ],
  "totalResults": 1
}

Workflow Tips

1. Always index first. Run kata-context index . before querying. All commands need an indexed database.
2. Use status to check health. Verify the index is current before relying on query results.
3. Choose the right search:
   • search — when you know the intent ("find error handling code") but not the name
   • find — when you know part of a symbol/file name ("user service")
   • grep — when you know the exact pattern ("TODO|FIXME")
4. Combine search + graph for full picture. Use search to find relevant symbols by meaning, then graph dependents to understand impact.
5. Use --json for parsing. When chaining commands or processing output programmatically, always use --json.
6. Use --quiet for scripting. When you only need a list of names or paths, --quiet gives clean output.
7. Re-index after significant changes. The index is a snapshot — re-index when files have changed.
8. Set OPENAI_API_KEY for semantic features. Without it, index still works (structural only) but search and recall won't.
9. Use remember for durable knowledge. Persist decisions, patterns, and learnings. They survive across sessions and are searchable via recall.
10. Memory has a git audit trail. Every remember, forget, and consolidate creates a git commit in the project repo. Use git log to see memory mutation history.

Watch Mode

kata-context watch [path]

Monitor source files and automatically re-index on changes.

# Start watching (human-readable events)
kata-context watch .

# JSON event stream (NDJSON)
kata-context watch . --json

# Custom debounce window
kata-context watch . --debounce 500

# Quiet mode (no event output, background operation)
kata-context watch . --quiet

Options:

• --debounce <ms> — Debounce window in milliseconds (default: 300)
• --json — Output events as NDJSON (one JSON object per line)
• --quiet — Suppress event output

Events emitted:

• start — Watcher initialized and ready
• change — File changes detected (includes file list)
• reindex-start — Incremental re-indexing triggered
• reindex-done — Re-indexing completed (includes duration)
• error — Error during watch/reindex (includes error code)

Error codes: WATCH_INIT_FAILED, WATCH_REINDEX_FAILED, WATCH_PROVIDER_ERROR

Stop with Ctrl+C (SIGINT) — the watcher shuts down cleanly.

Combined Retrieval

kata-context get "<query>" [--budget N]

Get an integrated context bundle assembled from structural, semantic, and memory retrieval within a token budget.

# Default budget (4000 tokens)
kata-context get "implement rate limiting"

# Custom budget
kata-context get "authentication handler" --budget 8000

# Filter by symbol kind
kata-context get "error handling" --kind function

# JSON output with full diagnostics
kata-context get "implement rate limiting" --json

# Quiet mode (raw content only)
kata-context get "implement rate limiting" --quiet

Options:

• --budget <tokens> — Token budget for results (default: 4000)
• --kind <kind> — Filter by symbol kind (function, class, etc.)
• --json — Full JSON output including diagnostics envelope
• --quiet — Raw content blocks only

How it works:

1. Runs structural (FTS + graph), semantic (vector search), and memory (recall) strategies in parallel
2. Deduplicates overlapping results by symbol ID
3. Reranks with configurable weights (structural 0.4, semantic 0.3, recency 0.15, memory 0.15)
4. Assembles results within the token budget (greedy fill from top-ranked)
5. Returns items with provenance labels (structural/semantic/memory)

JSON output includes a diagnostics envelope:

{
  "items": [...],
  "diagnostics": {
    "perStrategy": {
      "structural": { "status": "ok", "hits": 5, "timeMs": 12 },
      "semantic": { "status": "ok", "hits": 3, "timeMs": 145 },
      "memory": { "status": "skipped", "hits": 0, "timeMs": 0 }
    },
    "budgetUsed": 3800,
    "budgetTotal": 4000,
    "totalTimeMs": 158
  }
}

Degraded modes: If semantic fails (no API key), structural + memory results are still returned. If memory store is empty, it's skipped. Per-strategy status in diagnostics shows what happened.

Troubleshooting

| Error | Cause | Fix | |-------|-------|-----| | No database found | Index hasn't been run yet | Run kata-context index . first | | No semantic vectors indexed | Index was run without OPENAI_API_KEY | Set OPENAI_API_KEY and run kata-context index . | | OPENAI_API_KEY missing | Key not set in environment | export OPENAI_API_KEY=sk-... | | Model mismatch | Embedding model changed since last index | Run kata-context index . --full to re-index | | Symbol not found | Symbol name doesn't match any indexed symbol | Check spelling, use find to search by partial name | | ripgrep (rg) is not installed | grep command requires ripgrep | Install: brew install ripgrep or apt install ripgrep | | path does not exist | The specified project path doesn't exist | Check the path argument to index | | MEMORY_RECALL_EMPTY | No memories stored yet | Use remember to store memories first | | MEMORY_RECALL_MISSING_KEY | OPENAI_API_KEY not set for recall | Set the environment variable | | MEMORY_FILE_NOT_FOUND | Memory ID doesn't exist | Check the ID with recall or list memories | | MEMORY_CONSOLIDATE_TOO_FEW | Need at least 2 IDs to consolidate | Provide 2+ memory IDs | | WATCH_INIT_FAILED | Watcher couldn't start | Check path exists and permissions | | WATCH_REINDEX_FAILED | Re-index failed during watch | Check disk space and DB access | | WATCH_PROVIDER_ERROR | API provider error during re-index | Check API keys and connectivity | | Empty get results | No matching data | Run index first, check OPENAI_API_KEY for semantic results | | Budget too small | Budget can't fit any results | Increase --budget value |

Exit Codes

| Code | Meaning | |------|---------| | 0 | Success | | 1 | Error or no results found |