{"slug": "show-hn-heimdall-trust-verified-knowledge-layer-for-ai-coding-agents", "title": "Show HN: Heimdall – Trust-verified knowledge layer for AI coding agents", "summary": "Heimdall, a new open-source tool launched on Hacker News, provides a trust-verified knowledge layer for AI coding agents, labeling search results as STRONG, WEAK, REBUILT, or STALE/REMOVED to prevent agents from acting on dead paths. The tool uses a single-writer lock, content-hash reconciliation, and level-triggered updates to ensure graph convergence, with a `heimdall verify` command for CI drift checks.", "body_md": "**Your agent keeps rebuilding work you already did. Heimdall makes it stop.**\n\nEvery AI coding session starts cold. Grep across your repos can't answer *\"did\nI already solve this in another project?\"* — the answer lives in a different\ndirectory, described in prose, under a path you've never opened. The result:\n**the same work rebuilt three times.**\n\nHeimdall is a self-healing, **trust-verified knowledge layer** for AI coding\nagents. It watches what your agent does, keeps a semantic memory graph fresh\nacross every project you touch, and — the part nobody else builds — **labels\nevery search hit with a trust verdict** so your agent never acts on a dead\npath or a hallucinated match.\n\nEvery search result is verified against reality before your agent sees it:\n\n`STRONG`\n\n— path exists on disk, strong lexical coverage,**and** the file's actual content answers the query (content-aware scoring)`WEAK`\n\n— semantic match only; plausible but unverified`REBUILT`\n\n— file moved; Heimdall found it and re-anchored automatically`STALE`\n\n/`REMOVED`\n\n— dead path, logged and pruned so it stops ranking\n\nAn agent acting on a dead path is worse than no answer. Verdicts are what make the graph trustworthy enough to act on.\n\nForty agents can edit one file at once. The graph still converges to exactly\nwhat is on disk, because Heimdall never tries to infer *what changed*.\n\n**Level-triggered, not event-driven.** A hook, a watcher, or a script can only say \"look at this path\". It is never believed about*what*happened. The reconciler reads the file from disk and makes the graph match it. A missed hint, a duplicated hint, or a flatly wrong hint costs one`stat`\n\n.**Single writer by construction.** Every graph mutation goes through one`O_EXCL`\n\nlock. Two writers cannot exist, so there is no interleaving to race — the old delete-then-insert window where a file briefly vanished from the graph is gone.**Exact ownership.** Every node and edge belongs to exactly one path. A commit deletes and re-inserts all of that path's rows in one transaction, so a symbol you deleted cannot survive as a ghost.**Content hash is the oracle.** Same bytes, same depth ⇒ same graph. That is what makes reconciling twice identical to reconciling once, and it is why concurrent edits are harmless rather than merely unlikely to collide.**Order independence.** A cross-file edge to a symbol that is not indexed yet parks as a pending edge and resolves from either side, so the final graph does not depend on which file was reconciled first.**Audit as backstop.**`heimdall verify`\n\ncompares the journal against the filesystem and exits non-zero on drift — it is the accuracy claim as a command you can put in CI.`--deep`\n\nre-hashes and catches even a rewrite that preserved size and mtime.\n\nThe honest guarantee is **bounded-staleness convergence**, not instantaneous\ncorrectness: between an edit and the next reconcile pass, the graph is behind.\nIt is never *wrong* in a way that survives a pass.\n\n```\nheimdall daemon              # the single writer: watch, reconcile, audit on a timer\nheimdall reconcile           # converge now (one-shot; takes the same lock)\nheimdall reconcile --all     # deep audit + repair everything\nheimdall verify --deep       # read-only drift report; exit 1 if any. CI-safe\n```\n\nNodes are indexed at a depth. The default and the recommendation is **maximum**\n— the graph knows not just that a file exists but which functions and classes\nlive in it, at which lines, and what calls what.\n\n| Depth | Node knows |\n|---|---|\n`path` |\nthe file exists |\n`file` |\n+ name, language, size |\n`symbol` |\n+ every function/class/method and its line number |\n`graph` |\n+ the edges between them, within and across files |\n\n`max`\n\nresolves to whatever the machine can actually do. Symbol and graph depth\nneed tree-sitter; without it a path degrades to `file`\n\ndepth rather than\ndisappearing, and the next audit upgrades it automatically once tree-sitter\nappears. Asking for a depth above the machine's capability is honored as far as\npossible and reported as `clamped`\n\n.\n\n```\nheimdall depth                       # what this machine can do, and why\nheimdall depth src/server.ts         # requested vs effective depth for one path\n```\n\nExtraction is tree-sitter AST parsing, not an LLM call: depth costs CPU, never tokens.\n\n```\nnpm i -g heimdall\n\n# one-time: install the graft backend (local semantic-memory daemon)\n#   see https://github.com/tinygrad/graft — put the `graft` binary on PATH\n#   (e.g. ~/.local/bin/graft) and create ~/.graft/config.yaml:\n#   cp \"$(npm root -g)/heimdall/config/heimdall.yaml.example\" ~/.graft/config.yaml\n\n# wire it into your harness (pi | claude-code | codex | cursor | windsurf | all)\nheimdall init --harness claude-code\n\n# verify the backend is healthy\nheimdall doctor\n\n# search across every project you've worked in\nheimdall search \"excel tracker portfolio optimization\"\n\n# record reusable work when your agent finishes something\nheimdall insert --title \"poker jam_opt optimizer\" \\\n  --body \"~/Repos/poker-bot/tools — heads-up jam/fold EV optimizer\" \\\n  --keywords poker,optimize\n```\n\n`init`\n\n, `insert`\n\nand the harness wiring work immediately; `search`\n\nand\n`doctor`\n\nneed the graft backend installed separately (build from source —\nembedding model download included, so not instant). The vendored `vendor/graft/`\n\nis source + attribution, not a prebuilt binary.\n\n| Harness | Command | Integration |\n|---|---|---|\nPi |\n`heimdall init --harness pi` |\nnative extensions: `kb_search` /`kb_insert` /`kb_sync` tools, edit autosync, session orientation |\nClaude Code |\n`heimdall init --harness claude-code` |\nPostToolUse hook emits path hints + memory snippet |\nCodex CLI |\n`heimdall init --harness codex` |\n`AGENTS.md` search/insert instructions |\nCursor |\n`heimdall init --harness cursor` |\nrules file with search-first workflow |\nWindsurf |\n`heimdall init --harness windsurf` |\nrules file with search-first workflow |\n\nSee [docs/adapters.md](/ArihantDeva/heimdall/blob/main/docs/adapters.md) for what each adapter installs.\n\n| Component | File | Job |\n|---|---|---|\nCLI |\n`bin/heimdall.js` |\n`init` / `search` / `insert` / `doctor` / `daemon` / `reconcile` / `verify` / `depth` / `hint` |\nRanked search |\n`bin/kb-search.sh` |\ntop-k ranked candidates + graph walk, `--scope` filter |\nTrust verification |\n`bin/kb_search_verify.py` |\ncontent-aware `STRONG` /`WEAK` /`STALE` /`REBUILT` verdicts |\nReconciler |\n`bin/lib/reconcile.mjs` |\nlevel-triggered convergence: read disk, make the graph match |\nJournal |\n`bin/lib/journal.mjs` |\nauthoritative index: ownership, hashes, generations, dedup queue |\nSingle-writer lock |\n`bin/lib/lock.mjs` |\n`O_EXCL` lock every graph mutation passes through |\nDepth ladder |\n`bin/lib/depth.mjs` , `bin/lib/extract.mjs` |\n`path` /`file` /`symbol` /`graph` ; tree-sitter extraction |\nDaemon |\n`bin/heimdall-reconciler.mjs` |\nwatch + drain + periodic audit, holding the lock |\nEdit-log replay |\n`bin/sync-edits.sh` |\none-shot bootstrap: session edit logs → hints → reconcile |\nHint emitter |\n`extensions/kb-autosync.ts` |\nharness hook; appends \"look at this path\", never writes the graph |\nSearch guard |\n`extensions/kb-search-guard.ts` |\nwarns the agent after 3 grep-style searches without consulting memory |\nSession orientation |\n`extensions/kb-orient.ts` |\ninjects relevant prior work into the first prompt of a session |\nHealth & telemetry |\n`bin/kb-health.sh` , `bin/telemetry.sh` |\ndaemon health, index freshness, usage stats |\nStale pruning |\n`bin/kb-stale-scan.py` , `bin/kb-rehome.sh` |\ndead anchors get rehomed or removed |\nBackend |\n`vendor/graft/` |\nGraft (Apache 2.0) — local-first semantic memory daemon |\n\n```\nagent harness (Pi / Claude Code / Codex / Cursor / Windsurf)\n        │  hooks + tools\n        ▼\nHeimdall orchestration ── trust verification ── self-healing sync\n        │ thin CLI contract (insert/retrieve/explore/get/delete/stats)\n        ▼\nsemantic memory backend (Graft, vendored)\n```\n\n**Backends are pluggable.** Any store speaking the CLI contract works; Graft is\nthe vendored reference.\n\n- Node ≥ 22.5 (the journal uses the built-in\n`node:sqlite`\n\n),`bash`\n\n,`python3`\n\n- macOS today (launchd daemon management); Linux works with a manual daemon\n- Optional, for\n`symbol`\n\n/`graph`\n\ndepth: tree-sitter and the grammars for the languages you care about. Any Python 3 with them importable will do:Run\n\n```\npython3 -m venv ~/.heimdall/venv\n~/.heimdall/venv/bin/pip install tree-sitter tree-sitter-python \\\n  tree-sitter-javascript tree-sitter-typescript tree-sitter-go tree-sitter-rust\n```\n\n`heimdall depth`\n\nto see what the machine resolved`max`\n\nto. Without them everything still indexes, at`file`\n\ndepth.\n\n```\nnpm test          # 41 tests: CLI, adapters, trust verdicts, guard, plus the\n                  # reconciler invariants — 40 interleaved writers and 6 real\n                  # child processes against one file, idempotency, ABA/stale\n                  # commits, ownership retraction, order independence,\n                  # depth resolution, drift detect+repair, lock exclusivity\nnpx tsc --noEmit  # typecheck\n```\n\nThe concurrency tests are the point: if the single-writer or idempotency properties ever break, those are the tests that go red.\n\nv0.2.0 — adds the reconciler: a single-writer, level-triggered convergence loop with a content-hash oracle, exact per-path ownership, and a depth ladder that indexes symbols and call edges by line. Replaces the previous design, where hooks inferred changes from commands and wrote the graph directly from several processes at once.\n\nv0.1.0 shipped the packaged CLI, five harness adapters, content-aware trust verdicts, and a fresh-install-verified quickstart. Backend (Graft) is a separate install — see Quickstart.\n\nMIT. Independent project — not affiliated with Graft or its authors.", "url": "https://wpnews.pro/news/show-hn-heimdall-trust-verified-knowledge-layer-for-ai-coding-agents", "canonical_source": "https://github.com/ArihantDeva/heimdall", "published_at": "2026-08-22 02:02:14+00:00", "updated_at": "2026-08-22 02:13:55.820481+00:00", "lang": "en", "topics": ["ai-agents", "developer-tools", "ai-infrastructure"], "entities": ["Heimdall", "Hacker News"], "alternates": {"html": "https://wpnews.pro/news/show-hn-heimdall-trust-verified-knowledge-layer-for-ai-coding-agents", "markdown": "https://wpnews.pro/news/show-hn-heimdall-trust-verified-knowledge-layer-for-ai-coding-agents.md", "text": "https://wpnews.pro/news/show-hn-heimdall-trust-verified-knowledge-layer-for-ai-coding-agents.txt", "jsonld": "https://wpnews.pro/news/show-hn-heimdall-trust-verified-knowledge-layer-for-ai-coding-agents.jsonld"}}