hyponoia

# Hyponoia

> An open-source Model Context Protocol (MCP) server that indexes a codebase into a persistent knowledge graph of functions, classes, call chains, HTTP routes, and cross-service links. AI coding agents query the graph instead of reading files one by one, answering structural questions with roughly 120x fewer tokens (~3,400 vs ~412,000 across five structural queries). Parses 158 languages via vendored tree-sitter grammars, with Hybrid LSP semantic type resolution for Python, TypeScript/JavaScript, PHP, C#, Go, C/C++, Java, Kotlin, and Rust. It also generates semantic graph edges (SEMANTICALLY_RELATED for vocabulary-mismatch matches, SIMILAR_TO for near-clone detection) and supports semantic vector search via bundled nomic-embed-code embeddings compiled into the native executable — no API key, no Ollama, no Docker. Ships a native executable with an authenticated integration asset; the UI variant adds one content-addressed frontend pack. All processing is local — the embeddings run on-device; there is no embedded LLM and no API key.

## Key facts

- License: MIT, open source.
- Languages: 158 (158 vendored tree-sitter grammars compiled into the binary).
- Hybrid LSP type resolution: 10 language families (Python, TypeScript/JavaScript/JSX/TSX, PHP, C#, Go, C/C++, Java, Kotlin, Rust, Perl) — a lightweight C implementation of language type-resolution algorithms, structurally inspired by and compatible with major language servers including tsserver, pyright, gopls, Roslyn, Eclipse JDT, and rust-analyzer.
- MCP tools: 18 (index_repository, list_projects, index_status, delete_project, check_index_coverage, search_graph incl. semantic_query vector search, ask, search_code, get_code_snippet, trace_path (alias: trace_call_path), query_graph (Cypher), get_graph_schema, get_architecture, detect_changes, manage_adr, ingest_traces, record_memory, search_memory).
- `project` is OPTIONAL on every tool but `delete_project`. Omitted, the server uses the project of the working directory it was started in (the client spawns it, so that is the client's directory; the name derives from the absolute path with its leading separator dropped and every other separator as `-`, /home/u/repo -> home-u-repo), then the nearest indexed ancestor of it, then the single indexed project when there is exactly one. Several candidates and no signal returns a `which project?` error LISTING them rather than picking. Every answer carries `project` and `project_source` (supplied | derived from working directory <path> | the only indexed project). An explicit argument always wins; `delete_project` still requires one because a destructive tool does not infer its target.
- Two retrieval lanes. STRUCTURAL: search_graph/trace_path/query_graph over the graph, sub-millisecond and exact, able to answer questions about absence. SEMANTIC: `ask` takes ONE natural-language question and returns ranked declarations encoded whole by a transformer, so an answer can match code sharing none of the question's words.
- `ask` measurement, PRIMARY: CLARC, 1,245 distinct public C/C++ queries across 8 split-by-setting combinations (2,990 query-evaluations). The shipping encoder voyage-4-nano (346M params, Apache 2.0) beats the retired Qwen3-Embedding-0.6B (596M) on 7 of 8 splits, all significant, +4.62 to +19.23 NDCG@10; the 8th is a tie (+1.15, p = 0.227). This is the evidence the encoder swap was decided on. The 60-question frozen set is a SMOKE TEST, not a benchmark — nano is +0.100 recall@10 on it but a TIE on MRR@10 (p = 0.577) — and must not be quoted as the argument.
- `ask` measurement, the counterweight: on CoIR's CosQA (500 public queries) nano LOSES to the encoder it replaced by 3.55 NDCG@10 (−9.53%, CI [−6.24, −0.87], p = 0.0154) when both are run on the same lane. This is the one public corpus where the shipping model is worse. ATTRIBUTION AND LANE, because three harnesses are involved and they are not interchangeable: 39.44 is Qwen3 through our shipped binary and is the number this project quoted before 2026-08-12; 37.24 is the same Qwen3 weights in our PyTorch lane; 33.69 is nano in that PyTorch lane. Nano through the shipped binary has NEVER been measured on CosQA. Quoting 39.44 → 33.69 mixes a model change with a lane change and inflates the loss by about 60%. Against the CoIR paper's own column (BM25 13.96, Voyage-Code-002 29.79, BGE-Base 32.76, CodeR-1.5B 46.72, Gemini-embedding 50.24) read 33.69 as "not obviously worse than the paper's table", not as a win — it crosses a lane boundary. Against the 64.88 ceiling that CosQA's 86% duplicate text imposes on any content-based retriever, 33.69 is 52% of achievable and Qwen3's 39.44 was 61%. On CodeTransOcean-DL, where query and document are both code, `ask` scores 23.97 against BM25's 50.13 — a real boundary.
- `ask` is opt-in: it needs `hyponoia fetch-model` (voyage-4-nano, a 355 MB Q8_0 GGUF plus an 8 MB projection head, each pinned to one revision and SHA-256 verified) and `hyponoia embed`. Until that index exists it answers available=false with the remedy, never an empty result set.
- `ask(escalate=true)` brings a hosted embedding model into ONE question; off by default, never automatic. `ask.escalation.mode=query` (the DEFAULT) sends only the ~30-token question, encodes it with the hosted model and scores it against the LOCAL index — the code never leaves the machine — and is refused unless the local index and the hosted model share a MEASURED embedding space (voyage-4 family: nano/lite/large/4; voyage-code-3 and Qwen3 measured NOT shared; unmeasured families refused, because cross-space scoring returns confidently-ranked garbage with no error). `mode=index` queries a second, API-built index of the whole corpus (`hyponoia embed --escalation`). Neither mode falls back silently; every answer names `lane` (local | escalation-query | escalation-index), `query_encoder`, `index_encoder` and `key_custody`. WHOSE KEY PAYS is its own setting: tool calls are served by the long-lived per-account daemon, which reads the key from the environment IT was started with, so `ask.escalation.daemon_key` gates that — `refuse` by DEFAULT (escalation through a warm daemon is refused, naming the holder), `allow` means any local process of this user account that reaches the daemon can spend against that account without holding the key. Read per request, so revoking needs no restart; `hyponoia daemon status` shows the policy; the local lane reads no key and is unaffected. Query mode is licensed on quality (+0.2087 MRR@10 on the frozen 60; +0.444% RR, p 5.5e-05, on 8,122 CodeSearchNet-Go queries); its case over index mode is operational (no second index, no drift, no corpus-sized bill), not a quality margin — the two are indistinguishable at scale (p 0.62).
- Keyword semantic search: search_graph(semantic_query=[...]) scores an ARRAY of keywords against a static per-token nomic-embed-code table (768-dim) compiled into the binary; 11-signal combined scoring; fully local, no API key. This is a different lane from `ask`.
- Semantic & similarity edges: SEMANTICALLY_RELATED (vocabulary-mismatch matches) and SIMILAR_TO (MinHash + LSH near-clone / duplicate detection).
- Cross-repo intelligence: CROSS_* edges link nodes across multiple repos indexed in one store; multi-galaxy 3D layout and cross-repo architecture summary.
- Cross-service linking: HTTP route ↔ call-site matching, plus gRPC/GraphQL/tRPC detection and pub/sub channels (EMITS/LISTENS_ON for Socket.IO, EventEmitter, generic buses).
- Supported agents: 43 automatic/conditional client surfaces (37 automatically detected + 6 conditional/explicit): Claude Code, Codex CLI, Gemini CLI, Zed, OpenCode, Antigravity, Aider, KiloCode, VS Code, Cursor, Windsurf, Augment / Auggie, OpenClaw, Kiro, Junie, Hermes, OpenHands, Cline, Warp, Qwen Code, GitHub Copilot CLI, Factory Droid, Crush, Goose, Mistral Vibe, Qoder CLI, Kimi Code CLI, GitLab Duo CLI, Rovo Dev CLI, Amp, Devin CLI / Local, Tabnine, Continue / cn, Visual Studio, TRAE, Roo Code, Amazon Q Developer IDE, CodeBuddy Code CLI, IBM Bob IDE, IBM Bob Shell, Pochi, Pi, and Sourcegraph Cody.
- Agent profiles: documented custom-agent formats receive Scout (fast/provisional), Verify (default/task-directed), and Auditor (bounded/full verification) definitions. Every direct tier checks exact path/scope coverage with check_index_coverage and falls back to source for flagged gaps; unsafe child-MCP formats use explicit parent handoff. Kiro and Junie use positive-allowlist Scout/Analysis server profiles (7/13 tools; `ask` is Analysis-only); Qoder combines named-server selection with exact tier-specific MCP tool IDs, while Factory uses exact registered IDs without additive whole-server exposure. Foreign Junie aliases are preserved and force parent handoff.
- Performance: Linux kernel (28M LOC, 75K files) full index in 3 minutes → 4.81M nodes, 7.72M edges; Cypher queries in under 1ms.
- Distribution: the repository is PUBLIC and v0.3.0 is published — the first release carrying binaries (v0.2.4 shipped zero assets). Five archives, all UI-variant: hyponoia-ui-{linux-amd64,linux-arm64,linux-amd64-portable,linux-arm64-portable}.tar.gz and hyponoia-ui-windows-amd64.zip, each with a cosign bundle, plus checksums.txt and sbom.json. The install one-liners and direct archive downloads WORK. The PACKAGE MANAGERS DO NOT YET: Homebrew/Scoop/Chocolatey/AUR/winget manifests are in-tree with real checksums but are not submitted to their registries. No macOS and no ARM64 Windows download — build from source on macOS. Build from source: `scripts/build.sh`.

## Links

- Source code (GitHub): https://github.com/patalbansishashank/hyponoia
- Latest release: https://github.com/patalbansishashank/hyponoia/releases/latest
- Benchmark report: https://github.com/patalbansishashank/hyponoia/blob/main/docs/BENCHMARK.md
- The `ask` lane in full: https://github.com/patalbansishashank/hyponoia/blob/main/docs/ASK.md
- Documentation index: https://github.com/patalbansishashank/hyponoia/blob/main/docs/README.md