EDHIndex

Local-first hybrid code search engine with Knowledge Graph — zero telemetry, fully offline.

npm install -g edhindex
# or
npx edhindex <command>

Quick start

cd ~/your-project
edhindex init     # initialize index (pick model, index mode + MCP client)
edhindex start    # build index + start MCP server + watch for changes

Then ask any MCP client (OpenCode, Claude Code, Cline, Cursor, etc.) to search your codebase.

Supported file types

EDHIndex uses a pluggable Language Adapter architecture. Every language has its own adapter file. To add a new language, just create one adapter — no changes to the core engine.

42 adapters supporting 100+ file extensions — from programming languages to config files, documentation, documents, images, data formats, and infrastructure.

Tier 1 — Full symbol extraction (18 adapters)

| Language | Key | Extensions | Symbols indexed | |----------|-----|-----------|----------------| | TypeScript | ts | .ts, .tsx, .mts, .cts | functions, methods, classes, interfaces, enums | | JavaScript | js | .js, .jsx, .mjs, .cjs | functions, methods, classes | | Python | py | .py, .pyw | functions, classes | | Go | go | .go | functions, methods | | Rust | rs | .rs | functions, structs, traits, enums | | Java | java | .java | methods, classes, interfaces, enums | | Ruby | rb | .rb | methods, classes, modules | | C | c | .c, .h | functions, structs | | C++ | cpp | .cpp, .cxx, .cc, .c++, .hpp, .hxx, .hh | functions, classes, structs, enums | | C# | csharp | .cs | methods, classes, interfaces, structs, enums | | PHP | php | .php | functions, methods, classes, interfaces | | Swift | swift | .swift | classes, structs, enums, protocols, extensions, actors, functions, methods | | Kotlin | kotlin | .kt, .kts | classes, interfaces, objects, enums, functions, properties | | Dart | dart | .dart | classes, mixins, extensions, enums, functions, methods | | Scala | scala | .scala, .sc | classes, traits, objects, enums, functions, methods | | Haskell | haskell | .hs, .lhs | data types, type classes, instances, functions | | Solidity | solidity | .sol | contracts, interfaces, libraries, structs, enums, functions | | Lua | lua | .lua | functions, methods, tables, variables |

Note: Tier 1 adapters use tree-sitter WASM for full AST parsing. In runtimes where WASM loading fails, they gracefully fall back to paragraph-based text indexing so every file still gets indexed.

Tier 2 — Structural support (24 adapters)

| Language | Key | Extensions | What gets extracted | |----------|-----|-----------|-------------------| | HTML | html | .html, .htm | significant elements (section, nav, header, etc.) | | CSS | css | .css, .scss, .less | rule selectors, variables, media queries | | JSON | json | .json | object keys, nested structures | | JSON Variants | json-variants | .jsonc, .json5 | object keys, comments, nested structures | | YAML | yaml | .yaml, .yml | mappings, sequences, keys, anchors | | TOML | toml | .toml | tables, arrays, keys, values | | Markdown | markdown | .md, .markdown | headings, paragraphs, blockquotes, tables, lists, code blocks, frontmatter | | SQL | sql | .sql | tables, views, indexes, functions, foreign keys | | Vue | vue | .vue | components, template, script, style sections | | Svelte | svelte | .svelte | components, script, style, Svelte blocks | | Astro | astro | .astro | frontmatter, components, style, script | | Terraform | terraform | .tf, .tfvars | blocks, attributes, resources, variables | | Dockerfile | dockerfile | Dockerfile* | FROM, RUN, CMD, COPY, ENV, EXPOSE | | Salesforce | salesforce | .cls, .trigger, .page, .component, etc. | classes, triggers, components, metadata | | CSV | csv | .csv | headers, columns, data structure | | Config | config | .ini, .properties, .env, .conf, .cfg, .gitignore, .editorconfig | sections, key-value pairs | | Documentation | documentation | .rst, .adoc | sections, headings, directives, code blocks | | Documents | document | .pdf, .docx, .pptx | text extraction — paragraphs, sections, slides | | Spreadsheets | spreadsheet | .xlsx, .xlsm | sheets, rows, headers — parsed safely as OOXML (no SheetJS) | | SVG | svg | .svg | elements, IDs, classes, paths | | Images | image | .png, .jpg, .jpeg, .gif, .ico, .webp, .bmp, .tiff | metadata (format, dimensions, size) | | Text | text | .txt, .log | sections, paragraphs, log entries |

Generic fallback

Any file with an unrecognized (non-binary) extension goes through the GenericAdapter — splits content by paragraphs, indexes as plain text. Never crashes.

What gets skipped

• Binary/archive/media files (.exe, .dll, .so, .zip, .tar, .mp3, .mp4, etc.)
• Files larger than 10 MB
• Generated/minified files (*.min.js, *.min.css, *.generated.ts, *.g.ts, package.json, tsconfig.json, lockfiles)
• macOS system files (.DS_Store)
• Language artifacts (.pyc, .class, .jar)
• Credential-looking files — .env*, *.pem, *.key, id_rsa*, *credentials*, *secrets*, .aws/credentials, etc. Indexed content is queryable by any MCP client, so secrets are denied by default. Opt in (not recommended) with edhindex config indexSecrets true.

.edhindexignore

Add a .edhindexignore file at your project root (created automatically on edhindex init) with gitignore-compatible glob patterns to skip additional files. Supports # comments and ! negation.

# ignore generated code
src/generated/
*.log

.gitignore

edhindex init automatically adds .edhindex/ to your project's .gitignore (or creates one if none exists).

The root .gitignore is also honored during indexing — gitignored files are skipped (git already knows they aren't source). Disable with edhindex config respectGitignore false.

Indexing modes

EDHIndex supports two indexing modes, chosen during edhindex init (or via edhindex config indexMode):

Lazy (default — Recommended)

• Server starts immediately — no waiting for indexing to complete
• Files are indexed in small batches (3 files per batch, 500ms delay) in the background
• Already-indexed files are skipped — only new/changed files get processed
• Keeps the system responsive — never blocks CPU/IO

Full

• Indexes everything at once before starting the server
• Use when you want the full index available immediately after startup

Switch anytime:

edhindex config indexMode lazy
edhindex config indexMode full

Resource governor (adaptive memory throttle)

A ResourceGovernor samples process RSS + system free memory (~every 2s) and adapts indexing to the box: ok runs at full pace, soft (RSS over maxIndexRssMB, default 1536) halves batch size and doubles delay, hard (RSS over ~1.33× that, or <512MB system-free) parks the indexer until memory recovers and defers the search rerank leg — search still answers, marked degraded: ['rerank']. Sustained hard pressure (~5min) unloads the models entirely; they reload lazily on next use. Before indexing starts, a one-line warning fires if the configured model's measured footprint (estRssMB) + 256MB headroom exceeds free RAM. edhindex status and doctor report headroom; get_indexing_status exposes memory: {rssMB, freeMB, pressure, throttleFactor, reliefWaits, hardEvents, modelReleases} — the counters distinguish chronic pressure from a transient spike.

Containers: "free" is cgroup-aware — process.constrainedMemory() plus /sys/fs/cgroup/memory.{max,current} (v1 fallbacks included) mean a docker run -m 512m daemon trips hard at the container ceiling, not the host's free RAM.

Query path: searches are exempt from relief waits by design — a query embeds a few KBs and scans a bounded candidate set, so the only pressure-sensitive leg is the reranker, which is skipped under hard. There is no knob for this; the allocation profile doesn't justify one.

Every knob is config — defaults reproduce the historical pacing exactly:

edhindex config indexBatchFiles 3        # lazy-mode files per batch
edhindex config indexBatchDelayMs 500    # lazy-mode ms between batches
edhindex config embedBatchSize 8         # chunks per embed call
edhindex config modelIdleMs 300000       # idle ms before models unload
edhindex config maxIndexRssMB 1536       # governor soft threshold
edhindex config memoryGovernor false     # restore fixed pacing entirely
edhindex config watchSweepIntervalMs 600000  # idle tree re-hash reconciling dropped fs events (0 = off)

Live file watcher

When edhindex start runs (and watch: true in config, which is the default), a filesystem watcher tracks changes — a single recursive fs.watch on macOS (one file descriptor), chokidar elsewhere. On every save — removes old chunks for the file, re-parses, re-indexes. Debounced at 300ms.

Linked roots (multi-repo workspaces)

Index additional directories alongside the workspace:

edhindex config linkedRoots '["../shared-lib","/abs/path/to/other-repo"]'

Each linked root gets a short alias (its directory basename); indexed paths appear as <alias>/<relative-path> (e.g. shared-lib/src/util.ts) in search results, the knowledge graph, and import resolution — cross-repo imports resolve through the linked roots.

Search pipeline

     User query
         ↓
   ┌────────────────┐
   │  Keyword (BM25) │── SQLite FTS5 → top 30
   └────────────────┘
   ┌────────────────┐
   │  Vector (ANN)   │── transformers.js → LanceDB → top 30
   └────────────────┘
   ┌────────────────┐
   │  Memory recall  │── memory.sqlite found_in links → linked chunks
   └────────────────┘
         ↓
   ┌────────────────┐
   │  RRF fusion     │── reciprocal rank fusion over all three rankings
   └────────────────┘
         ↓
   ┌────────────────┐
   │  Reranker       │── cross-encoder → final top N
   └────────────────┘
         ↓
     Results with matchType: keyword | vector | hybrid | memory
                   + confidence: high | medium | low   (or an honest no-match)

• Keyword: SQLite FTS5 with BM25 scoring (porter + unicode61 tokenizer)
• Semantic: @huggingface/transformers embeddings → LanceDB ANN search
• Hybrid: top 30 BM25 + top 30 vectors → reciprocal rank fusion → rerank → top 10
• Memory fusion: memories matching the query contribute their found_in-linked chunks as a third RRF ranking, so chunks with no keyword/vector hit can still surface (see Memory-fused search)
• Reranker: Xenova/ms-marco-MiniLM-L-6-v2 cross-encoder (configurable via edhindex config)

Relevance confidence & honest no-match

Nearest-neighbor retrieval always returns something — including confident-looking junk for queries with no real answer. EDHIndex labels every result with the evidence behind it instead of hiding the uncertainty:

| Confidence | Evidence behind the result | |-----------|---------------------------| | high | keyword/path/symbol match and vector agreement | | medium | keyword or identifier evidence without vector corroboration | | low | vector-only or memory-only — a nearest-neighbor guess | | none | nothing relevant — response is noMatch: true with an empty list |

• Per-index calibration: after each indexing run, fixed off-topic probe queries establish a corpus-specific floor; weak vector-only candidates below it are filtered. Results with lexical/path/symbol evidence are never filtered, and low results are labeled rather than dropped, so paraphrase recall is preserved.
• Surfaced in MCP structuredContent, edhindex search --json (confidence, noMatch, legStats), and the library's searchResultsToJSON(). The MCP response tells agents to rephrase with code identifiers when confidence is low.

Embedding model tiers

| Tier | Model | Dimensions | Download size | Best for | |------|-------|-----------|--------------|----------| | balanced (default) | bge-base-en-v1.5 | 768 | ~114 MB | strongest relevance that stays fast | | fast | GTE-Small | 384 | ~33 MB | modest hardware / huge repos | | code | EmbeddingGemma 2 | 768 | ~198 MB | code retrieval (text + code prompts, 8k ctx) | | jcode | Jina v2 Code | 768 | ~162 MB | code-specialized, 8k ctx, symmetric (no prompts) | | max | BGE-M3 | 1024 | ~560 MB | multilingual, 100+ languages |

Switch with edhindex config model <tier> — a full re-index (or edhindex index --reembed) happens automatically on the next run.

Models trained for asymmetric retrieval (bge instruct, EmbeddingGemma) get the required query/document prompt prefixes automatically — query and chunk embeddings are never produced with the wrong prompt.

Pre-download a model without indexing: edhindex models --download --tier code.

Quantization variants — the code tier (EmbeddingGemma 2) ships five precision levels; pick one at init or anytime:

edhindex models                              # lists variants + sizes
edhindex config dtype q8                     # higher fidelity than q4 default
edhindex models --download --dtype q8        # fetch a specific variant

q4 ~174MB (default, fastest) · q4f16 ~157MB · q8 ~314MB (higher fidelity) · fp16 ~542MB · fp32 ~1.08GB (full precision). Changing dtype rebuilds embeddings on the next index — different precision, different vectors. All models share one system cache (~/.cache/edhindex/huggingface), so each variant downloads once per machine, not per project.

Error logging

All indexing errors and per-file status are written to .edhindex/edhindex.log — not printed to console during indexing. Each file gets a trace:

[2026-07-28T06:18:00.571Z] [INDEXED] Sample.java
[2026-07-28T06:18:09.713Z] [FAILED] sample.dart
  Error: ... (stack trace)
...
[2026-07-28T06:18:32.088Z] [INFO] Index summary: 80 files indexed, 11 failed, 2919 chunks total

Knowledge Graph

Every symbol becomes a node. Imports, exports, and hierarchy become edges. Four graph modes (switch in the UI):

| View | Description | |------|-------------| | Force | Physics-based node layout | | Hierarchy | Directory tree structure | | Circle | Circular arrangement | | Grid | Grid layout |

Commands

edhindex kg --rebuild    Build the knowledge graph from the index
edhindex kg --stats      Node/edge counts by type
edhindex kg --serve      Open interactive browser at localhost
edhindex kg --write      Write standalone HTML → .edhindex/knowledge-graph.html

Built on tree-sitter + SQLite + Cytoscape.js — all local, no telemetry, no cloud.

Node/edge types

Node kinds: workspace, folder, file, module, class, interface, enum, struct, trait, function, method, variable, constant, property, import, export, namespace, package, constructor, extension, field, type_alias, document, section, table, selector, rule, actor, object, protocol

Edge kinds: contains, imports, exports, inherits, implements, calls, references, defines, belongs_to

Memory Graph

Persistent, queryable agent memory graph — stores entity facts, observations, decisions, tasks, questions, and notes across sessions, linked directly to code symbols in the Knowledge Graph.

Commands

edhindex memory add --label "Auth Decision" --type decision --content "Use JWT for session auth"
edhindex memory search "JWT"
edhindex memory list --type observation
edhindex memory get <id>
edhindex memory delete <id>
edhindex memory stats
edhindex memory prune
edhindex memory clear
edhindex memory export -o memories.json
edhindex memory import memories.json

Memory Node Types

• entity: modules, services, APIs, people
• observation: performance findings, bugs, quirks
• decision: architectural choices, trade-offs
• task: active or past goals
• fact: verified codebase facts
• question: open questions or TODOs
• note: general notes and context

Memory-fused search

Memories are not a separate silo — the search engine consults them on every query. Memories whose content matches the query contribute their found_in-linked files/symbols as an additional ranking, ranked by confidence × recency decay (30-day half-life) × access count. A chunk that surfaces only this way gets matchType: memory, and with explain: true every result reports which memories boosted it.

• Control at the query level: search_codebase accepts useMemory (boolean) and explain (boolean); the CLI has edhindex search --no-memory.
• Control at the config level: edhindex config memoryBoostEnabled true|false and edhindex config memoryBoostWeight <number> (weight 0 disables the contribution; higher weights make memory-linked chunks outrank keyword/vector hits more easily).
• Injection gate: a memory can boost chunks already in the retrieval pool, but it can only add a new file to the results when the memory itself had lexical (keyword) evidence for the query — a purely semantic memory match can no longer pull unrelated files into an off-topic search.
• Expired memories (past expiresAt) are never served by search; remove them permanently with edhindex memory prune.

Commands

| Command | What it does | |---------|-------------| | edhindex init | Initialize .edhindex/ — pick model, index mode + MCP client | | edhindex start | Build/update index + start MCP server (stdio) + file watcher | | edhindex stop | Stop the running daemon for this workspace | | edhindex logs | Tail the daemon/indexer log (-n, --follow) | | edhindex open | Print the MCP client config + open the file manager at .edhindex/ | | edhindex serve | Shared daemon over Streamable HTTP — one index, many MCP clients (--port) | | edhindex index | Just build/update the index (no server). --reembed re-embeds stored chunks without re-parsing | | edhindex search <query> | CLI hybrid search (--json → confidence/noMatch/legStats, --min-score, --file <glob>, --lang <language>) | | edhindex status | Index stats (--json for machine-readable output) | | edhindex eval | Retrieval eval: golden query set → recall@k/MRR + per-query latency p50/p95; also supports no-match sets (expect: []) with a false-positive rate (--init, --set, --write-baseline, --fail-below, --fail-regression, --fail-false-positive-rate, --explain, --strict, --memory — memory seeds into an isolated temp store, never your real memory) | | edhindex config | View/update settings | | edhindex models | List embedding models (--download to pre-fetch) | | edhindex kg ... | Knowledge graph ops: --rebuild, --stats, --serve (live viewer), --write, --snapshot <name>, --diff [name] | | edhindex memory ... | Persistent agent memory graph operations | | edhindex graph | Static SVG dependency graph | | edhindex doctor | Diagnostics | | edhindex reset | Delete the entire .edhindex/ |

MCP Tools

When edhindex start is running, any MCP client can call:

| Tool | What it does | |------|-------------| | search_codebase | Hybrid search with file/language filters, memory-boosted ranking (useMemory, explain), format (full/signature/skeleton) and maxTokens result shaping — returns per-result and response-level confidence plus noMatch | | get_file_outline | File structure — symbols with kind + line ranges, no code bodies | | find_symbol | Locate symbol definitions by name/kind across the codebase | | find_references | Candidate call sites for a symbol (tree-sitter call edges) | | get_dependencies | A file's imports and dependents from the knowledge graph | | get_indexing_status | Live indexing progress — pending/indexed/failed counts | | get_graph | Full knowledge graph (nodes + edges) | | get_node | Node details + neighbors + linked memories | | search_graph | Search nodes by name | | get_graph_stats | Graph statistics | | memory_add | Record persistent memory (entity, decision, fact, etc.) | | memory_get | Retrieve memory by ID with code links | | memory_search | Full-text & tag search over memories | | memory_link | Link memory to code symbol in Knowledge Graph | | memory_update | Update memory content, tags, or confidence | | memory_list | List memories by type/recency |

Client setup

During edhindex init, pick your MCP client and the config file is created automatically:

• OpenCode → opencode.json
• Cline → .cline/mcp.json
• Roo Code → .roo/mcp.json
• Claude Code → .mcp.json
• Cursor → .cursor/mcp.json
• Windsurf → .windsurf/mcp_config.json
• GitHub Copilot / VS Code → .vscode/mcp.json (servers key)
• Continue → .continue/config.json

For edhindex serve (Streamable HTTP), point the client at the daemon URL instead of a command — e.g. .mcp.json:

{ "mcpServers": { "edhindex": { "type": "http", "url": "http://127.0.0.1:3939/mcp" } } }

Requirements

• Node.js 20+

Security

See SECURITY.md for what's indexed, the local/loopback threat model, indexSecrets semantics, token handling, and per-tool MCP annotations.

License

MIT