Graph-Augmented
Code Intelligence Engine

A local code-retrieval engine that parses Python and C++ into semantic CodeUnits, combines lexical and dense retrieval with program structure, and compiles explainable results into token-budgeted context.

  • Python
  • C++
  • Tree-sitter
  • SQLite / FTS5
  • FAISS
  • RRF
  • Static Analysis

286 tests · Python + C++ · Local-first · M0–M10 complete

One engine, multiple structural layers

Current implemented architecture — not a roadmap.

Source Repository → LanguageAdapter
Python OR C++ → Symbols / CodeUnits → Static Relations / CodeGraph
Storage SQLite + FTS5 FAISS FlatIP
Query ladder Lexical → Dense → Hybrid → Graph Augmentation → Structured Reranking → Context Compiler

Incremental maintenance path

SHA-256 ChangeSet → incremental semantic analysis → relation refresh → transactional persistence → selective vector reuse

Semantic Units

Whole functions/classes/methods — not arbitrary text chunks.

Hybrid

Lexical + dense rankings fused with reciprocal rank fusion.

Graph

Depth-1 RESOLVED structural neighbors support candidate ranking.

Context

Whole CodeUnits packed under an explicit token budget.

The same query, five retrieval strategies

Loading showcase query…

Gold target: store.save_order

Lower rank is better.

Ranking decisions are inspectable

The engine does not only return a similarity score. Structured reranking records the prior graph rank, per-relation RRF contributions, directional evidence, and final rank delta.

Captured from aicode search --mode reranked --explain 
symbol: store.save_order
rerank: #3 → #5 (delta -2)

contributions:
  graph_base  rank=3  rrf=0.015873
  calls       rank=5  rrf=0.015385

evidence:
  checkout.finalize_checkout [rank 1]
  CALLS · seed_to_candidate
checkout.finalize_checkout CALLS store.save_order
  • Hybrid rank 2
  • Graph rank 3
  • Reranked rank 5

Intentionally a negative structural example — graph fusion displaced the gold target.

A frozen benchmark, including negative results

24 hand-labeled queries · 11 files · 53 CodeUnits · Python

Source: committed canonical evaluation artifacts

What the evaluation found

Dense retrieval performed best in aggregate on the included benchmark. Graph-neighbor fusion often displaced already-correct text results, and the structured reranker sometimes amplified that reordering.

This is benchmark-specific evidence, not a universal claim.

24 Frozen queries
6 × 4 Categories
Top 10 Evaluation depth
MiniLM Dense model
5125c8fa…611ec2de SHA-256 frozen definition

Recompute what changed — reuse what did not

Avoided semantic-analysis and embedding work — not wall-clock speed claims.

Source: committed canonical evaluation artifacts

Retrieval ends at an LLM-ready context boundary

Whole CodeUnits · greedy skip-to-fit · overlap suppression · no partial source truncation · simple-lexical-v1 is an estimator, not a vendor tokenizer.

Token budget 1000 / 1000
Selected: 10 / 20 candidates Omitted: 10
Example selected CodeUnits From final local demo — not live browser computation 
checkout.finalize_checkout
checkout.compute_order_subtotal
policies.ChargePolicy
store.save_order
notifications.notify_order_confirmed
validation.validate_order_customer

Language-specific analysis, shared retrieval infrastructure

Python

  • users.normalize_email
  • checkout.finalize_checkout
  • store.save_order

Relations: CALLS · IMPORTS · INHERITS · CONTAINS

C++

  • pricing::calculate(int)
  • pricing::calculate(double)
  • ui::Widget::Widget(int)
  • ui::Widget::~Widget()
  • ui::Widget::operator==(const Widget&) const
  • @filelocal:local_a.cpp::<anonymous>::helper()
Overload-safe identity calculate(int) ≠ calculate(double)

Tree-sitter syntax analysis, not compiler-grade C++ semantics. No C++ REFERENCES baseline. Single language per index snapshot.

Python ─┐
        ├→ SQLite / FTS → FAISS → Hybrid → Graph → Rerank → Context
C++ ────┘
286tests
2languages
5retrieval modes
24frozen queries
53benchmark CodeUnits
11benchmark files

M0–M10 complete

  1. M0 Foundation
  2. M1 Parsing
  3. M2 Code Graph
  4. M3 Lexical Index
  5. M4 Dense + Hybrid
  6. M5 Graph Retrieval
  7. M6 Explainable Reranking
  8. M7 Context Compiler
  9. M8 Incremental Index
  10. M9 C++
  11. M10 Evaluation

Built as retrieval infrastructure — not a chatbot.

View GitHub Explore Benchmark Results View Canonical JSON