Semantic: A Local Rust Service for Deterministic Code Retrieval and AI Integration

Semantic is a local Rust service designed to provide deterministic code retrieval by symbol, span, and logic graph. It offers a semantic-first integration guide for RooCode, KiloCode, Codex, and Claude, along with middleware policy controls and end-to-end flow diagrams. The service includes modules for engine, shared contracts, parser, tree-sitter extraction, storage, SQLite + Tantivy indexer, repo indexing, orchestration, retrieval, operation handlers, watcher, incremental file updates, and API. The API is implemented using Axum JSON service and includes semantic layers such as logic nodes, persisted control/data-flow edges, semantic node labels, and graph-backed clustering/ranking.

To run the service, use the command cargo run -p api -- ./test_repo. The service binds to $SEMANTIC_API_BASE_URL. Semantic also offers an optional Project Summariser Add-On, which generates a compact, LLM-ready project map at session start without requiring an LLM call. This add-on is built entirely from the existing index and supports both JSON and markdown formats. To use the Project Summariser, you can make a curl request to $SEMANTIC_API_BASE_URL/project_summary?max_tokens=800&format=markdown or use the MCP retrieve tool with the operation GetProjectSummary.

Another optional add-on is the Token Tracking Add-On, which tracks token usage per task across retrieve, ide_autoroute, and edit. To enable this feature, copy .semantic/token_tracking.example.toml to .semantic/token_tracking.toml and set enabled = true. The token tracking dashboard can be run using the command cargo run -p token_tracking -- ./test_repo. Telemetry data is written as NDJSON to .semantic/token_tracking/events.ndjson and ingested into .semantic/token_tracking/tracker.sqlite. Privacy defaults include strict (metrics only, hashed paths, no prompt bodies), balanced (small redacted snippets), and debug (richer local capture) modes.

Semantic provides a Two-Tool MCP Surface, which exposes two primary tools: retrieve and ide_autoroute. The retrieve tool covers all retrieval and graph operations, while the ide_autoroute tool handles intent routing (task) or action dispatch (action + action_input). Actions include debug_failure, generate_tests, apply_tests, and analyze_pipeline. All 27 legacy named tools remain available for backward compatibility but are now routed through retrieve or ide_autoroute instead of depending on separate primary entrypoints.

Key API endpoints include POST /retrieve for all retrieval and graph operations, POST /ide_autoroute for intent routing and action dispatch, and PATCH /edit for safe edit planning/execution. The default retrieval behavior is reference_only=true (structured references first, raw code minimized) and single_file_fast_path=true recommended for obvious single-file edits. Adaptive retrieval breadth is used to avoid over-fetching on high-fanout symbols.

The latest A/B Benchmark Update (2026-03-27) shows improvements in step savings (27.78% fewer estimated developer steps) compared to token savings per call. The test suite enhancements in the 2026-03-27 run include equalized success thresholds, new retrieval_quality block, and validated_success_with_pct per-task retrieval_ms, context_coverage, and misdirection_risk fields. Local estimate_tokens in A/B test is aligned with budgeter (chars/3).

Semantic also implements reasoning retrieval, which combines logic-node and dependency traversal. The Cognitive Retrieval Pipeline includes API, Planner, Retrieval Engine, Budgeter, and Context Assembler. The get_planned_context operation adds query intent detection, deterministic retrieval planning, token-budget-based context selection, and adaptive small-repo bypass (files < 50).

Graph semantics implemented in Semantic include persisted control-flow edges, persisted data-flow edges with variable names, semantic labels on logic nodes, clustered logic regions, and hybrid graph ranking that blends symbol, dependency, and graph-density signals. Phase 5 Maturity features include SQLite-backed planned-context cache with automatic invalidation on index changes, policy-driven token caps and adaptive retrieval thresholds, anti-bloat controls for small single-file tasks, quality-gated A/B evaluation with validated patch/test signals, p95/p99 latency alerts and cache hit-rate alerts in GetPerformanceStats, and full MCP compatibility through the two primary tools: retrieve and ide_autoroute.

Module Graph and Hierarchy Phase-4.5 adds module-aware indexing and retrieval, including module detection from src/ and lib/ structure, module dependency inference from symbol dependency edges, hierarchical repo map retrieval (modules -> files -> symbols), and module-aware planning and budgeting priority. Workspace Intelligence Phase-5 adds repository registry and dependency graph, repo-aware symbol/dependency records, semantic symbol search fallback, workspace-level reasoning context retrieval, and AST cache and invalidation engine modules.

Safe Editing and Routing (Phase-6) includes new modules such as impact_analysis, safe_edit_planner, patch_engine, llm_router, policy_engine, patch_memory, refactor_graph, code_health, architecture_analysis, improvement_planner, evolution_graph, and knowledge_graph. The safe edit pipeline involves Agent/IDE -> Edit Request -> Impact Analysis -> Safe Edit Planner -> LLM Router -> Patch Engine -> Validation/Policy -> Apply Patch. The representation includes ASTTransform (engine-native edit intent) and UnifiedDiff (preview/apply format). Config files include .semantic/edit_config.toml, .semantic/llm_config.toml, .semantic/llm_routing.toml, .semantic/model_metrics.json, .semantic/policies.toml, and .semantic/validation.toml. The edit endpoint can be accessed using the command curl -X PATCH "$SEMANTIC_API_BASE_URL/edit" -H "content-type: application/json" -d '{"symbol":"retryRequest","edit":"add exponential backoff","patch_mode":"preview_only","run_tests":true}'.

Patch memory endpoints include curl "$SEMANTIC_API_BASE_URL/patch_memory?symbol=retryRequest", curl "$SEMANTIC_API_BASE_URL/patch_stats?repository=my-repo", and curl "$SEMANTIC_API_BASE_URL/model_performance". Refactor status endpoint can be accessed using the command curl "$SEMANTIC_API_BASE_URL/refactor_status". Refactor snapshots are stored in .semantic/refactor_snapshots/. Evolution endpoints include curl "$SEMANTIC_API_BASE_URL/evolution_issues?repository=core_api", curl "$SEMANTIC_API_BASE_URL/evolution_plans?repository=core_api", and curl -X POST "$SEMANTIC_API_BASE_URL/generate_evolution_plan" -H "content-type: application/json" -d '{"repository":"core_api","dry_run":true}'.

An example request can be made using the command curl -X POST "$SEMANTIC_API_BASE_URL/retrieve" -H "content-type: application/json" -d '{"operation":"get_function","name":"retryRequest"}'. Storage paths include ./.semantic/semantic.db and ./.semantic/tantivy/. Index performance stats can be found in ./.semantic/index_performance.json. Retrieval policy template is located at .semantic/retrieval_policy.example.toml. The watcher reindexes changed files incrementally. Runtime docs use environment placeholders such as $SEMANTIC_API_BASE_URL; do not commit local URLs, API keys, or tokens.

For more information, visit the Semantic GitHub repository.