Internal Tool

Cortex

Ask the codebase anything.

Explore Features

Features

Local RAG, Every Repo, Zero Leakage

Cortex ingests every markdown file across all 73 AVIAN repos into a Milvus 2.4 vector store, embeds with Voyage-3-large (1024-dim, COSINE/HNSW), and serves retrieval-augmented answers via Anthropic Sonnet 4.6 or Haiku 4.5. A 30-second asyncio indexer loop watches every repo's HEAD SHA and re-embeds only the files that actually changed — no full re-index on every tick. Six MCP tools wire Cortex directly into Claude Code sessions so any active session can search, retrieve, and interrogate the corpus on demand. Patent-adjacent content is filtered at three independent layers before it ever touches the vector store. Binds to 127.0.0.1 only — no auth layer, no telemetry, no cloud egress of code.

ReplacesCursor codebase chat, Sourcegraph Cody, GitHub Copilot Chat, Phind

Vector Store

Milvus 2.4 — HNSW, COSINE, 1024-Dim

  • Milvus Standalone

    Cortex shares the fleet Milvus 2.4 standalone instance on localhost:19530 (managed by tools/supporting-services). No separate vector DB to run or maintain — it's already part of the development stack.

  • cortex_docs Collection

    Markdown chunks land in the cortex_docs collection. Schema: id, repo, path, chunk_index, content (up to 65 535 chars), section heading trail, embedding float_vector(1024), git_sha, file_sha, updated_at. Scalar indexes on repo and path for filtered retrieval.

  • HNSW Index — M=16, ef=200

    The embedding field uses an HNSW index with M=16, ef=200, and COSINE metric. Nearest-neighbor search is sub-millisecond at monorepo scale, and the index survives Milvus restarts without rebuild.

  • Deduplication by File SHA

    Every chunk carries a file_sha (full-file SHA) alongside the blob-level git_sha. The indexer skips re-embedding a file whose file_sha hasn't changed, even if a git merge replays its tree entry under a new commit.

  • Source Code Collection (v2)

    A second collection cortex_code — same 1024-dim schema, Voyage-code-3 embeddings — extends coverage to source files. Identical HNSW parameters; separate collection keeps doc and code retrieval independently tunable.

Embeddings

Voyage-3-Large Primary, BGE-M3 Fallback

  • Voyage-3-Large (Primary)

    All production embeddings use voyage-3-large via the Voyage API. 1024-dimensional dense vectors, optimized for long-document retrieval. Configured via CORTEX_EMBEDDING_MODEL; the VOYAGE_API_KEY env var is required when this backend is active.

  • BGE-M3 Local Fallback

    When the Voyage API is unreachable, Cortex automatically falls back to BGE-M3 running fully locally — same 1024-dim output, no external calls. Swap the default permanently by setting CORTEX_EMBEDDING_BACKEND=bge.

  • Voyage-code-3 for Source

    The cortex_code collection uses voyage-code-3 — Voyage's code-specific embedding model — rather than the general-purpose large model. Retrieval accuracy on function signatures, class names, and import paths is meaningfully better than a general-purpose embedder.

Indexer

30-Second Git-Diff Loop

  • Monorepo Discovery

    On boot, the asyncio indexer walks the AVIAN root recursively to find every .git/ directory. Discovered repos and their last-seen HEAD SHAs are written to state/repo_state.json. Deleting that file forces a full re-index on the next tick.

  • SHA-Gated Incremental Updates

    Every 30 seconds (configurable via CORTEX_POLL_INTERVAL_S), the indexer runs git rev-parse HEAD per repo. If the SHA hasn't changed, the repo is skipped entirely. Only changed repos pay the cost of a git diff --name-status <old>..<new>.

  • File-Level Delta Indexing

    A and M events from the diff trigger re-embedding of the affected file only. D and R events delete the old chunks from Milvus. First-time repos get a full git ls-files '*.md' seed pass; subsequent ticks are strictly incremental.

  • mtime Fallback for Non-Git Folders

    Directories without a .git/ root (currently only the AVIAN root itself) fall back to mtime-based scanning. The same chunk + embed + upsert path runs; only the change-detection mechanism differs.

  • Fault Isolation

    Individual file errors are logged and skipped — the daemon keeps going. Repo-level errors pause that repo for one tick and retry automatically. The indexer never crashes the FastAPI process over a bad file.

  • Live WebSocket Events

    The WS /ws/indexer endpoint streams real-time indexer events to connected clients: file added, file updated, file deleted, tick complete, per-repo chunk counts. The Cortex frontend subscribes on load and renders a live activity feed.

RAG & Answering

Sonnet 4.6 + Haiku 4.5, Prompt-Cached

  • Sonnet Mode — k=12

    Default /api/v1/ask calls retrieve k=12 chunks via Milvus and pass them to Claude Sonnet 4.6 (claude-sonnet-4-6). The system prompt and retrieved chunks are prompt-cached — repeated questions against the same context window are cheap.

  • Fast Mode — Haiku, k=6, 3-Sentence Cap

    Pass mode: 'fast' to switch to Claude Haiku 4.5 with k=6 chunks and a 3-sentence answer cap. Latency drops from ~2 s to ~400 ms for quick lookups. The MCP ask tool exposes both modes directly.

  • Citation-Enforced Answers

    The system prompt (cached) instructs the model to cite every claim with a [repo:path#section] reference drawn from the retrieved chunks. The model is forbidden from inventing — if the answer isn't in the retrieved context, it must respond with “not in index.”

  • Header-Aware Chunking

    Markdown is split by heading hierarchy first (H1 → H2 → H3), then by a 500-token budget with 50-token overlap. Fenced code blocks are never split mid-block. Each chunk carries a section field with the full heading trail (Architecture > Data Model) so retrieval context is unambiguous. Chunks below 100 tokens are merged with the previous chunk.

MCP Integration

Six Tools, Zero Auth, Stdio Transport

  • search — Vector Retrieval

    search(query, k=10, repo=None, path_glob=None) — run a Milvus nearest-neighbor search and return the top-k chunks with their repo, path, section, and content. Optional repo and path_glob filters narrow scope to a single repo or subtree.

  • ask — RAG Answer

    ask(question, mode='sonnet'|'fast', repo=None) — retrieve relevant chunks and return a model-generated, citation-grounded answer. Claude Code sessions call this to interrogate the monorepo mid-conversation without leaving the terminal.

  • list_repos & list_files

    list_repos() returns every indexed repo with its chunk count and last-indexed timestamp. list_files(repo, glob='**/*') returns the file list for a given repo, filtered by an optional glob pattern. Both are read-only — no writes go through MCP tools.

  • get_file & stats

    get_file(repo, path) returns the full raw contents of any indexed file. stats() returns total chunks, total files, total repos, and per-repo last-tick timestamps. All six tools are thin HTTP clients against http://127.0.0.1:3445 — the MCP server requires the backend to be running.

  • One-Line Registration

    Register Cortex in any Claude Code session with claude mcp add cortex python -m cortex_mcp.server --cwd <mcp-server dir>. Stdio transport, zero auth, no daemon to manage separately. The MCP server process is launched by Claude Code on demand.

Privacy & Security

Local-Only, Patent-Excluded, Three-Layer Filter

  • 127.0.0.1 Bind, No Auth

    The FastAPI backend binds exclusively to 127.0.0.1 (controlled by CORTEX_BIND — do not change without understanding the implications). No auth layer exists by design. Exposing Cortex off-localhost is a separate, future epic — not a config flag.

  • Repo-Level Exclusion

    Repos listed in SENSITIVE_REPO_NAMES (currently avian-patent-portfolio) are never discovered, never listed in list_repos(), and never embedded. The scanner doesn't touch them at all. Additional repos can be excluded via the CORTEX_EXCLUDE_REPOS env var (comma-separated).

  • Path-Substring Exclusion

    SENSITIVE_PATH_SUBSTRINGS (currently {“patent”}) applies a case-insensitive bare-substring check to every file's repo-relative path before embedding. Intentionally aggressive — a file named patently_obvious.md also matches, and that's fine. False positives are cheap; false negatives are expensive.

  • Purge-on-Tick Sweep

    Every time the indexer daemon wakes up, it runs a _purge_sensitive_paths() pass that deletes any Milvus chunk whose path field matches a sensitive substring — regardless of how it got there. This is the belt-and-suspenders pass for content embedded before the filter was added.

Accessibility

Built for Everyone

  • WCAG 2.1 AA Compliance

    4.5:1 contrast for body text, 3:1 for large text and UI components, in both light and dark themes.

  • Keyboard Navigation

    Every interaction reachable via keyboard. Logical tab order, visible focus indicators, Escape-to-dismiss for modals.

  • Screen Reader Support

    VoiceOver, NVDA, and JAWS tested. Semantic HTML, ARIA labels, live regions for dynamic updates.

  • Reduced Motion

    Respects prefers-reduced-motion. Usable at 200% zoom. Touch targets meet 44x44 minimum.

How It Works

Index, Search, Answer, Act

  1. Step 1: Index

    The asyncio indexer daemon polls every repo's HEAD SHA every 30 seconds. Changed files are chunked by heading hierarchy, embedded with Voyage-3-large, and upserted into Milvus. Deleted files purge their chunks. Sensitive paths are excluded and swept at every tick.

  2. Step 2: Search

    A query hits POST /api/v1/search (or the search MCP tool). Milvus runs COSINE nearest-neighbor over the 1024-dim embedding space and returns the top-k chunks with repo, path, section, and content — optionally filtered to a single repo or path glob.

  3. Step 3: Answer

    Retrieved chunks and the question are composed into a prompt-cached Anthropic API call. Sonnet 4.6 (k=12) or Haiku 4.5 fast mode (k=6, 3-sentence cap) returns a citation-grounded answer. The model is instructed to respond “not in index” rather than hallucinate.

  4. Step 4: Act

    Six MCP tools expose every capability to Claude Code sessions mid-conversation: vector search, RAG answering, repo enumeration, file listing, raw file retrieval, and index stats. Sessions query the live corpus without leaving the terminal or copy-pasting file paths.

Technical Specifications

Under the Hood

  • Backend

    • FastAPI (Python 3.12+) on port 3445
    • asyncio indexer daemon — single task, 30 s poll, fault-isolated per file
    • pymilvus client to shared Milvus 2.4 on localhost:19530
    • Anthropic SDK — Sonnet 4.6 default, Haiku 4.5 fast mode
    • Voyage Python SDK — voyage-3-large primary, voyage-code-3 for source
    • Prompt caching on system prompt + retrieved chunks
    • State persisted to state/repo_state.json (repo path → last SHA + chunk counts)
    • Binds to 127.0.0.1 — no auth layer by design

  • Frontend

    • React 19 + TypeScript (strict) + Vite on port 3444
    • Tailwind CSS + @avian/design-system tokens and components
    • Live indexer activity feed via WS /ws/indexer
    • Search and ask interfaces with citation rendering
    • Light and dark mode

  • RAG & Index

    • Milvus 2.4 standalone — HNSW, COSINE, M=16, ef=200
    • 1024-dim float vectors (voyage-3-large / voyage-code-3)
    • BGE-M3 local fallback when Voyage API is unreachable
    • Chunking: 500-token target, 50-token overlap, 100-token merge floor
    • Header-hierarchy-first split (H1 → H2 → H3); code blocks never bisected
    • Section heading trail stored per chunk for unambiguous retrieval context
    • cortex_docs (markdown) + cortex_code (source) collections
    • Scalar indexes on repo and path for filtered search

  • MCP Server

    • Python stdio transport — zero auth, launched by Claude Code on demand
    • Six tools: search, ask, list_repos, list_files, get_file, stats
    • Thin HTTP client against http://127.0.0.1:3445
    • Read-only — no writes via MCP tools
    • One-line registration: claude mcp add cortex python -m cortex_mcp.server

  • Privacy

    • 127.0.0.1-only bind — no network egress of code or docs
    • Repo-level exclusion via SENSITIVE_REPO_NAMES (patent portfolio excluded)
    • Path-substring exclusion via SENSITIVE_PATH_SUBSTRINGS (case-insensitive)
    • Purge-on-tick sweep deletes any sensitive chunk that slipped through earlier passes
    • Additional exclusions via CORTEX_EXCLUDE_REPOS env var
    • No telemetry, no cloud sync of indexed content

Development

100% Built by Claude

Every tool in the Renkara fleet was built by Claude (Anthropic) working alongside a single human supervisor. Every line of code, every test, every deployment: AI-authored with human direction. The leverage factor across the fleet runs in the 20x–50x range, with individual sessions regularly exceeding 100x.

See the daily leverage records for per-task numbers across the full build history.