From 1ad6953044406ceb86fe9bd262de7853c5913ed6 Mon Sep 17 00:00:00 2001 From: ajianaz Date: Thu, 23 Jul 2026 08:51:32 +0700 Subject: [PATCH] docs: update changelog + cli-reference + roadmap for Phase 1-3/Brain Mode --- CHANGELOG.md | 36 ++++++++++++++++++++++++++++++++++++ docs/cli-reference.md | 25 ++++++++++++++++++++----- docs/roadmap.md | 11 +++++++++++ 3 files changed, 67 insertions(+), 5 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index c98a3ee..15ea84c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,42 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +### Highlights + +- **Brain Mode — hybrid code search.** `cora brain ` combines FTS5 keyword search, usearch vector similarity (HNSW), and graph BFS proximity into a single ranked result set via RRF fusion (k=60). Index-time embeddings use a zero-dependency static token method (256d) — no model download, no GPU. +- **tree-sitter AST extraction + call edges.** Schema v3 adds an `edges` table storing caller→callee relationships. When `cora index` runs with `--features tree-sitter`, it extracts function calls from AST nodes, enabling `cora trace` and `cora arch`. +- **`cora trace` and `cora arch` commands.** Trace symbol call chains (depth-limited) and display architecture overview (module breakdown, edge types, top connectors) from the indexed call graph. +- **Static token embedding engine.** Zero-dependency bag-of-tokens hashing (256d) for code symbol embeddings — suitable for near-duplicate detection and semantic search without external models. +- **Global index directory.** The symbol database migrated from `.cora/graph.db` (per-project) to `~/.codecora/cora-code/graph.db` (per-user), shared across all projects. +- **Renamed `cora-cli` → `cora-code`.** Binary is now `cora`, crate is `cora-code`. + +### Added + +- **Phase 3 — Brain Mode** (#362) + - `CodeVectorIndex` — persistent usearch HNSW vector index with fs2 file locking, key↔symbol mapping, and disk serialization + - `brain_search()` — hybrid search: FTS5 + usearch KNN (cosine, top-50) + graph BFS (depth-2 from FTS hits) → RRF k=60 fusion + - Schema v4: `embedding_tier`, `embedding_dims`, `embedding_model`, `last_embedded_at` columns on `projects` table + - Index-time embedding: all symbols embedded via static tokens during `cora index` + - CLI: `cora brain [--json] [--limit N]` + - MCP tool: `cora.brain_search` — semantic code search for AI coding agents +- **Phase 2C — `cora trace` and `cora arch`** (#358) + - `cora trace ` — trace call chains from a symbol (depth-limited BFS on call edges) + - `cora arch` — architecture overview: module breakdown, edge types, top connectors +- **Phase 2 — tree-sitter AST extraction + Schema v3** (#356) + - tree-sitter AST node extraction for Rust, Python, JavaScript, TypeScript, Go, Java + - Schema v3: `edges` table (caller_id, callee_id, edge_type) storing call relationships + - Gated behind `--features tree-sitter` (default build does not include tree-sitter) +- **Phase 1 — Static token embedding engine** (#354) + - Bag-of-tokens hashing: 256d vectors from code text, zero external dependencies + - Pre-trained nomic-embed-code vocabulary included (768d, reserved for Phase 5) + - `tokenize_code()`, `embed_code()`, `cosine_similarity()` public API +- **Global index migration** (#355) + - Symbol database moved from `.cora/graph.db` to `~/.codecora/cora-code/graph.db` + - `CODECORA_HOME` env var override for custom data directory +- **Binary rename** (#338) + - Crate renamed `cora-cli` → `cora-code` + - Binary name: `cora` + ## [0.7.0] - 2026-07-16 ### Highlights diff --git a/docs/cli-reference.md b/docs/cli-reference.md index a7f5832..13cfef8 100644 --- a/docs/cli-reference.md +++ b/docs/cli-reference.md @@ -61,13 +61,15 @@ Complete command reference for the cora CLI. | `cora debt --estimate` | Show estimated fix time | | `cora debt --since v0.4.5` | Filter by git tag or date | | `cora debt --branch main` | Filter by branch | +| `cora arch` | Architecture overview — modules, edge types, top connectors | +| `cora trace` `` | Trace call chains from a symbol (depth-limited BFS) | +| `cora brain` `` | Hybrid search: FTS5 + vector + graph → RRF fusion | +| `cora brain` `--json` | Brain search as JSON | +| `cora brain` `--limit N` | Max results (default: 20) | +| `cora index` | Index project symbols into SQLite + usearch | +| `cora index --rebuild` | Rebuild index from scratch | | `cora completion` `` | Generate shell completions (bash/zsh/fish) | | `cora mcp` | Start MCP server for AI coding agents (Claude Code, Cursor, Windsurf) | -| `cora debt` | Show tech debt report from review history | -| `cora debt --json` | Debt report in JSON format | -| `cora debt --trend` | Quality score trend graph | -| `cora debt --since ` | Filter by date or git tag | -| `cora debt --branch ` | Filter by branch name | ## Quick Examples @@ -106,3 +108,16 @@ $ curl -fsSL https://raw.githubusercontent.com/codecoradev/cora-code/main/instal # Then review with memory: $ cora review --staged --memory --learn ``` + +```bash +# Index your project and search with Brain Mode +$ cora index +$ cora brain "error handling" +$ cora brain "TokenEmbedding" --json --limit 5 +``` + +```bash +# Trace call chains and view architecture +$ cora trace main +$ cora arch +``` diff --git a/docs/roadmap.md b/docs/roadmap.md index 7acd9cd..a6a8765 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -104,5 +104,16 @@ Query layer built on top of the v0.6 index — call graph traversal, test impact ## Future — What's Next +### Brain Mode Roadmap + +- [Phase 1](https://github.com/codecoradev/cora-code/pull/354) — Static token embedding engine (256d) — ✓ Done +- [Phase 2](https://github.com/codecoradev/cora-code/pull/356) — tree-sitter AST + schema v3 edges table — ✓ Done +- [Phase 2C](https://github.com/codecoradev/cora-code/pull/358) — `cora trace` + `cora arch` — ✓ Done +- [Phase 3](https://github.com/codecoradev/cora-code/pull/362) — Brain Mode hybrid search (usearch + RRF) — ✓ Done +- [Phase 4](https://github.com/codecoradev/cora-code/issues/360) — Uteke integration upgrade → Planned +- [Phase 5](https://github.com/codecoradev/cora-code/issues/361) — Voyage-4-Nano ONNX (opt-in, 1024d) → Deferred + +### Other + - [#117](https://github.com/codecoradev/cora-code/issues/117) Lightweight agent follow-up — 1 capped tool-call — → Planned - [#132](https://github.com/codecoradev/cora-code/issues/132) GitHub App backend MVP in Rust (Axum) — → Planned