Heimdall

Your agent keeps rebuilding work you already did. Heimdall makes it stop.

Heimdall gives AI coding agents persistent memory across every repository and project you work on — so the question "did I already solve this in another project?" gets answered by one verified search instead of twenty minutes of grep, find, and ls loops.

The problem it solves

1. Memory that doesn't live in one repo. Every other memory tool is per-project. But your work isn't: the Excel tracker pattern you built last month solves the CSV-parsing problem in today's repo. Heimdall indexes everything you touch into one semantic graph, so knowledge follows you across repositories, languages, and months.

2. Orientation time, cut to seconds. A fresh agent session burns dozens of bash commands just figuring out the lay of the land — ls, grep, re-reading files it read last week. Heimdall injects the relevant prior work into the session's first prompt and backs a single kb_search call: ranked, scoped, verified. Fewer commands, fewer tokens, faster first useful action.

3. Zero token spend, zero GPU. Memory maintenance is a local daemon: file watching, tree-sitter AST parsing, sqlite. Indexing a file costs CPU only — never an LLM call. Retrieval is hybrid ranked search (lexical + semantic + graph walk) over locally-computed embeddings. Your context window stays for your actual work.

4. Retrieval you can act on. Semantic memory tools return plausible matches; Heimdall re-verifies every hit against the filesystem at query time and labels it:

• STRONG — path exists on disk, strong lexical coverage, and the file's actual content answers the query (content-aware scoring)
• WEAK — semantic match only; plausible but unverified
• REBUILT — file moved; Heimdall found it and re-anchored automatically
• STALE / REMOVED — dead path, logged and pruned so it stops ranking

An agent acting on a dead path is worse than no answer. Verdicts are what make the graph trustworthy enough to act on.

How a session changes

Without Heimdall:

$ grep -r "portfolio optimization" .            # wrong repo, 40s
$ find ~/work -name "*.py" | xargs grep -l optimizer   # 2 min
$ ls ~/work/... ; cat notes.md ; ...         # 15 commands later

With Heimdall:

$ kb_search "portfolio optimization jam optimizer"
   1. [STRONG] portfolio optimizer — ~/work/quant-bot/src — EV-optimizer entry point
   2. [STRONG] excel report builder — ~/work/reports/excel — 276-session tracking table

One call. Verified paths. Straight to work.

How it compares

Heimdall is the only one built for the actual workflow: many repos, many months, one agent session at a time, on hardware you already own.

FAQ

Does my code leave my machine? No. Indexing is tree-sitter parsing + local embeddings on CPU. Search runs against your local daemon. Nothing phones home.

Do I need a GPU? No. The embedding model (bge-m3) runs on Apple Silicon / any modern CPU.

How is this different from grep? Grep finds strings you already know exist. Heimdall answers "have I solved anything like this before?" across every project you've touched, ranked and verified against what's actually on disk right now.

What if a file moves or gets deleted? The reconciler notices on its next pass. Moved files are re-homed automatically (REBUILT verdict); deletions retract exactly their own nodes. A stale path never ranks again.

Does it work with my agent? One command wires it into pi, Claude Code, Codex, Cursor, or Windsurf. Anything that can run a CLI can use search/insert directly.

Is it production-ready? It runs daily on this author's machine across ~12,800 live nodes with a 166-test suite guarding the concurrency invariants. v0.2.0. LongMemEval benchmark harness is in bench/ (in progress).

Roadmap

• v0.1 — packaged CLI, five harness adapters, trust verdicts
• v0.2 — single-writer reconciler, depth-ladder indexing (symbols + call edges)
• LongMemEval-S score ≥ 0.90 published from bench/ (baseline S 0.740 reproduced)
• One-command graft backend install (heimdall init --backend)
• Linux daemon packaging
• MCP server mode

Contributing

PRs welcome — see CONTRIBUTING.md. The concurrency invariants are tested; break them and the suite goes red before you do.

Quickstart

npm i -g @arihantdeva/heimdall
heimdall init --harness claude-code   # or pi | codex | cursor | windsurf | all

That's it for install + harness wiring (init, insert work immediately).

Ranked search and doctor need the graft backend — one extra step:

# build graft from source, put the binary on PATH, then:
cp "$(npm root -g)/@arihantdeva/heimdall/config/heimdall.yaml.example" ~/.graft/config.yaml
heimdall doctor                        # should print HEALTHY
heimdall search "excel tracker portfolio optimization"

On macOS the backend runs as the launchd job com.graft.daemon (template: launchd/com.heimdall.backend.plist.example).

Alternative backend: Mnemosyne

Ranked search also supports mnemosyne-oss (SQLite-backed agent memory) as the retrieval backend. Graft remains the zero-config default; select mnemosyne per-invocation or persistently:

pip install mnemosyne-memory            # or: uv pip install mnemosyne-memory
HEIMDALL_BACKEND=mnemosyne heimdall search "preferences"        # one-off
# persistent:
python3 -c 'import json,pathlib; p=pathlib.Path.home()/".heimdall/config.json"; c=json.loads(p.read_text()) if p.exists() else {}; c["backend"]="mnemosyne"; p.write_text(json.dumps(c,indent=2))'
heimdall search "preferences"

Resolution order: $HEIMDALL_BACKEND > ~/.heimdall/config.json backend key > graft. Pin a non-PATH binary with MNEMOSYNE=/path/to/mnemosyne. Mnemosyne results flow through the same ranked/verified output as graft hits.

Demo

Real session output (abridged):

$ kb_search "portfolio optimization jam optimizer"
== retrieve (hybrid ranked): portfolio optimization jam optimizer
   1. [STRONG] cov83%  portfolio optimizer — ~/work/quant-bot/src
      EV-optimizer entry point, edited 2026-08-14
   2. [WEAK]   excel report builder — ~/work/reports/excel

Every hit carries a trust verdict computed against the live filesystem — not a cached embedding score.

Design history

v0.1.0 hooks inferred graph mutations by regex-parsing bash commands and writing the graph from every hook process. It collapsed: writes it didn't recognize were invisible, concurrent hook processes raced delete+insert, and a misparse wrote wrong data as fact. v0.2.0 replaced all of it with a single-writer, level-triggered reconciler: nothing ever tells the graph what changed, only that a path might have. The reconciler reads the file from disk and makes the graph match.

The trust verdict layer came from the same lesson one level up: even a perfect graph lies if its anchors rot (directories get reorganized aggressively). So search results are re-verified against the filesystem at query time, with self-healing (rehome) for moved files.

Star History

If Heimdall saved you a rebuild, a star helps other agents' humans find it.

Architecture / how it works

                 ┌─────────────────────────── harness integrations ───────────────────────────┐
                 │  Pi: extensions/kb-*.ts          Claude Code: PostToolUse hook             │
                 │  (kb-tools, kb-autosync, kb-orient, kb-search-guard)   Codex/Cursor/Windsurf │
                 └───────────────┬──────────────────────────────┬─────────────────────────────┘
                                 │ only ever appends hints      │
                                 ▼                              ▼
                     ~/.heimdall/hints.jsonl        heimdall CLI (bin/heimdall.js)
                                 │                     init / insert / hint / verify / depth
                                 ▼                                    │
   ┌───────────────────────── THE SINGLE WRITER (holds O_EXCL lock) ───┘
   │  bin/heimdall-reconciler.mjs  (daemon: fs watch + hint ingest + drain loop + audit timer)
   │        │ drain()  reads hint queue → reconcilePath() per path
   │        ▼
   │  bin/lib/reconcile.mjs  — level-t