CLAUDE.md git:20261030.44dda86A

Immutable. This exact content never changes and is served at /api/v1/blob/61911133f5be5707.

# Engram — context for Claude Code

**What this is:** a graph-based, durable, inspectable long-term project memory for AI coding assistants (Claude Code first). Local-first, user-owned, graph-first UI. The **reasoning/decision memory** layer (why/decided/what-bit-us) — not a code-structure graph; the wedge is the editable IDE-embedded graph pane + conflict surfacing + local. The line since 0.8.0: *the most powerful and feature-rich inspectable graph long-term memory for software development with AI agents, based on reproducible research.*

**THE GRAPH IS THE MEMORY OF RECORD — this file is only rules and a keyword index.** The session brief is auto-injected and opens with the **Current cycle** (open work stamped with the working version); `search` engram before any non-trivial work and follow the write-verdict protocol. Details, rationale, gotchas, and the full history live in this repo's graph (`.engram/graph.tepin`, daemon on 8787) and the eval workbench graph (`eval/.engram`, project `eval`, scientific ontology Claim/Method/Question/Finding/Source/Task). PLAN.md was retired 2026-08-04 (merged here); `PLAN §…` references in code comments point at git history.

## Hard rules (locked — don't relitigate without reason)
- Open-source, MIT; optimize for docs & DX. Product name **"Engram Alpha"**, binary `engram-alpha` (repo/plugin namespaces stay `engram`; JetBrains package `dev.techtheist.engram` — don't rename).
- **Rust** backend (rmcp, rusqlite bundled, sqlite-vec, fastembed, tepindb) — no Node runtime dep. **Vue 3.5 + TS + Vite + Bun**, Pinia, Tailwind 4, Vue Flow; `bun run lint` / `lint:style` in `frontend/`.
- Embeddings/models **local-only**; **no LLM in the daemon, ever** (encoder-only mechanisms); models nominate, people judge.
- **Retrieval changes cite a measured `eval/` run or they don't ship** (since 0.8.0).
- **9 node types (8 + Tombstone since 0.9.0) / 7 sentence-shaped verbs** on the default ontology; no new types, no `relates_to`; durability governs staleness; high-value edges are `replaces`/`conflicts-with`. Per-graph ontology/policy config exists since 0.7.0, but THIS repo's graph stays on the default ontology permanently.
- **Hard delete is user-only** (pane); MCP deliberately has no delete/register/pin tools. Writes are silent; transparency is the pane. One workspace version for every crate, stamped from the tag; `claude-plugin/.claude-plugin/plugin.json` must match (test-enforced).
- Multi-user & repo sync: **out of scope permanently** (future enterprise product). Dogfood on the **aggressive** skill variant (relaxed is the user default). Eval ladder max **1500 notes**.

## Where things go
`crates/engram-core` (engine, Store trait + sqlite/tepin drivers, policy, config, cortex) · `crates/engram-mcp` (rmcp tools) · `crates/engram-http` (axum API + embedded pane) · `crates/engram-cli` (`engram-alpha`: serve/mcp/doctor/setup/migrate/stop) · `frontend/` · `eval/` (engram-eval bench) · `eval/knowledgedrift/` (a pointer README only since 2026-09-16 — **KnowledgeDrift** lives in its own repo **github.com/techtheist/knowledgedrift**, main = v2: generator vendored, worlds frozen, engram-core a rev-pinned git dep behind `--features arms`; a local `.cargo/config.toml` `[patch]` points it at this checkout while a cycle is open; the gate/knob probes are uncommitted `examples/` there; that repo never mentions how the bench changed engram; old receipts `eval/results/*-knowledgedrift-*`) · `engram-jetbrains/`, `engram-vscode/` · `skills/engram/{aggressive,normal,relaxed}` + `claude-plugin/` (verbatim copies, sync-tested).

## Workflows & sharp edges
- **Pane/daemon rebuild: `scripts/deploy-pane.sh` only** (never hand-chain build/install/restart); after any redeploy, `/mcp` reconnect — live stdio sessions keep the OLD binary and stale tool descriptions.
- **Cycle open:** `set_version` in the graph + bump `Cargo.toml` workspace version and `claude-plugin/.claude-plugin/plugin.json` together; record the cycle's plan as an open Intent (it then leads the brief).
- **Release:** CHANGELOG section (one `## v<version>` per release) → push → `gh workflow run draft-release.yml -f version=X.Y.Z` → publish the draft. Bump the graph's working version (`set_version`) when a cycle OPENS, not at release. Sharp edges: `cargo fmt` before the release commit; CI's clippy is newer (`cargo +<CI-version> clippy`); delete stale drafts by release id, never by tag (Caution `00d6s063tpjx`); a `startup_failure` dispatch is re-dispatched, a starved-runner flake gets `gh run rerun --failed` (Caution `00bywotv5tx7`); never `cp -f` over an executed binary on macOS (Caution `00byqnk4w09h`).
- **E2e suites:** `crates/engram-cli/tests/{e2e,e2e_wiring,e2e_encryption}.rs` (harness `e2e_common/`), ride `cargo test --workspace`. Screenshots: `scripts/screenshots.sh` (local only, never CI); a surface missing from `frontend/demo/data/` is missing from the docs too.
- **Eval:** `cargo run -p engram-eval --features fastembed -- --series|--ladder|--sizes N|--tricks|--posttune|--floor|--bench|--chains|--window|--shapes|--longmemeval s` — receipts in `eval/results/`; `--distractors 0` = question-everything mode; `--longmemeval` downloads SHA-pinned into `eval/data/` (gitignored).
- Search-before-write; every write response is a verdict (matched → merge, suspects → judge now, warnings → check canon).

## Chronicle (one line per release — `search` with `during_version` or read CHANGELOG.md for the story)
- **0.10.4** (OPEN, opened 2026-10-30) — hotfix for #17: the Linux release binary builds on a pinned `ubuntu-24.04` runner again (glibc floor 2.38; `ubuntu-latest` had moved to 26.04 and 0.10.3 demanded GLIBC_2.43). Cycle Intent `00fkv3ygzu8a`.
- **0.10.3** (RELEASED 2026-10-30 at c4d83dc, opened 2026-10-29) — field fixes and a docs/tests pass: `.engram/` already ignored in any form is left alone (`gitignore.rs`, `git check-ignore` first, #12); System Info names a selected project's folder and database (#13); every `window.confirm` is a pane modal (`ModalDialog` + `confirmDialog()`; IDE webviews swallow the native one) and the Feed's delete asks just-delete vs leave-a-Tombstone with a note (#14); loopback POSTs keep a full reply despite a reset (the flaky `process_model` test, and `stop`); the GPU card painter breaks after hyphens like Chromium; a home-launched core hands out its own engine for `home` (`open_home` used to re-open home.tepin, wait out the 3 s lock retry and fail — every project brief lost its home section, 3 s late, and `project: "all"` skipped home). Cycle Intent `00fih2n6z1my`.
- **0.10.2** (RELEASED 2026-10-18 at a12106f, opened 2026-10-16) — selection focus on the graph (`graph/focus.ts`: three hop rings widen ×2/×1.4/×1.16 and draw on top, the rest dims, eased in the shader, written in place per selection); the Feed fades by notes from the current card (Engram Purple blurs from two out) with one gliding selection ring, solid cards; a scripted Playwright session at 5k / 1920×1080@2 drove the canvas fixes — card-font-only recalibration, `ui-dragging` ignored by the theme observer, per-verb edge styles, the atlas repaint loop after minimap flights (repaint only for sharper, reclaim a layer), half-size paints during fast slides; edges no longer trigger a relayout. Cycle Intent `00euwdlgy3xh`.
- **0.10.1** (RELEASED, opened 2026-10-15) — the graph canvas on WebGL2 (`frontend/src/components/graph/`): GPU cards with Canvas2D-painted text calibrated against the HTML card, HTML twin for selected/hovered, shelf atlas with zoom tiers, greeked far zoom, instanced bezier edges, cached glass blur, layout in a worker keyed on graph shape; Vue Flow (`GraphFlow.vue`) stays the no-GPU / lost-context fallback; edges culled to the view, still at bar zoom; zoom-out floor = fit. The Feed mounts only a window over a measured height map (`components/feed/`). Skyline splits components >300 nodes into communities (dagre dummy-node blowup), and polls keep unchanged node objects (`mergeById`). Bench: demo `?stress=1000|5000`.
- **0.10.0** (RELEASED 2026-10-15, opened 2026-10-13) — Tasks: a working list beside the graph (`tasks.rs`; never searched/embedded/scanned), five statuses, one level of groups, wake/close rules (version / date / `node:<id>`, release titles auto-close), brief `## Tasks`, MCP `add_tasks`/`update_task`/`list_tasks`, HTTP `/tasks`, the pane's 4th screen. Cycle Intent `00epajnh9mbt`.
- **0.9.12** (RELEASED 2026-10-11 at 572affc, opened 2026-10-10) — skills ~70% shorter and self-updating (stamped copies refresh unless edited; `skillsync.rs`), Cursor wiring, a warned rebind on `brief(project)`, presets keep tuned settings (`POST /config/presets/{id}`), README "when Engram helps"; `eval --knobs` showed keyword weight / knee don't move oblique recall (embedder is the untested lever). Cycle Intent `00ejh98mwe6w`.
- **0.9.11** (RELEASED 2026-10-03 at 1d61c3a, opened 2026-09-28) — Match IDE (the pane takes VS Code's / JetBrains' live theme; static skins cut to Engram Purple / IDE Light / IDE Dark); Checkup sweeps that explain empty results, finish across runs and reach below the floor via the title check; the weak line held out from its own transplant source (it had pinned at 0.95 on this graph); embedding off the write lock (`eval --writes`); the bridge answers while its core starts. Ladders run with `--distractors 0` (Caution `00e387ajvpga`). This machine's graph stays on Laya for dogfooding; every bench runs tasksource, which stays the default.
- **0.9.10** (RELEASED 2026-09-28 at 8332639) — grounded answers (`standing` on every hit, in the pane too); endorsements rank twins (twin order + endorsement clock, `eval --authority`); audit undo (pane/HTTP only); write judging off the engine lock; MCP sessions follow a replaced store; reproducible weak line; doctor knows the plugin; CI on Node 24.
- **0.9.9** (RELEASED 2026-09-24 at ffbcd1a) — contradictions propagate along inheriting edges (`inherits` verb role, hint `inherited`); Laya int4 / multilingual selectable judges (tasksource stays default; exports at huggingface.co/techtheist/laya-onnx); `eval --shapes`; brief gains Current cycle + `bodies` / `canon_order`; numeric MCP args accept strings; the Claude Code plugin ships its MCP server (`mcp --wired-only`, rung `unwired`); sweeps release the engine lock per node (a Laya sweep froze the core); this file slimmed (old chronicle in git history).
- **0.9.8** (released) — unbound sessions refuse writes (issue #11); `GET /guide` operator's manual.
- **0.9.7** — the icon arrives; plugins say "Engram Alpha".
- **0.9.6** — the bench spoke lowercase: subject guard v3, clause read, tombstone title channel, duplicate guard (KnowledgeDrift v2 816 @500).
- **0.9.5** — KnowledgeDrift born (own repo since); title-NLI nomination path.
- **0.9.4** — ForgetEval + rake test; hits carry the tombstone role; knee cliff refuses 0.
- **0.9.3** — the pane fits any width.
- **0.9.2** — tombstones guard the write path.
- **0.9.1** — SelectMenu, Bob hooks, screenshot pipeline, docs sweep.
- **0.9.0** — Tombstone type, custom fields, at-rest encryption.
- **0.8.13** — identity-checked engine cache, honest stop, version handshake; schemas teach.
- **0.8.11** — `brief(project)` binds; Windsurf + Devin wiring. **0.8.10** — session-diverse delivery. **0.8.9** — set_project, NLI scoreboard.
- **0.8.8** — one heavy core, light bridges, binding ladder. **0.8.7** — search learns time. **0.8.6** — dual JetBrains artifacts, update awareness. **0.8.5** — first field reports. **0.8.4** — the history layer. **0.8.3** — batch width 2, fp32 embedder. **0.8.2** — merge_nodes, LongMemEval, chains. **0.8.1** — knee trim, weak line, tasksource NLI. **0.8.0** — measured not promised.
- **0.7.x** — eval harness, customization, timeline. **0.6.x** — TepinDB, hub, federation. **0.5.x** — local cortex. **0.4.x** — trust v2. **0.3.0** — plugin. **Phase 0–1** — core graph.

## Now
The brief's **Current cycle** section is the live worklist; `list_open` has everything. The old consolidated roadmap (`00b7jwku2hxm`) was retired as obsolete on 2026-10-10; it can still be read for backlog history. Machine core on 8787; after `scripts/deploy-pane.sh`, `/mcp` reconnect.