Levandor

Scope Recommendation — Narrow ai-project-brain to a Reconciler

3 min read

A day of knowledge-graph research on 2026-09-07 landed on a concrete recommendation for this project: narrow it from “graph database application” to a single reconciler job, and drop grafeo. The full reasoning lives in knowledge-graph-research-2026-09-07.

This is a recommendation, not a decision

Nothing here has been decided or acted on. The project remains a scaffold as described in ai-project-brain. No code was changed, no dependency was removed. Treat this note as input to a decision the user still has to make. The alternative on the table is to drop the project entirely and trial trace-mcp instead, which already implements the same three verdicts for its own decision table.

For Agents

Three findings that change what this project should be:

  • The reconciler is the only thing worth building. Nothing off the shelf resolves this vault’s note conventions against a code index. Everything else in the graph stack has a credible existing tool.
  • grafeo is unnecessary for that job. SQLite suffices. See grafeo-feature-matrix for what grafeo’s embedded feature set actually buys, none of which the reconciler needs.
  • The graphtest / rustc_driver approach is superseded. rust-analyzer scip produces stable symbols without a nightly pin. Do not revive the HIR walker.

Estimated size: 150 to 300 lines.

What the reconciler does

Notes carry a code_refs anchor in frontmatter — repo plus path plus qualified symbol, replacing bare lib.rs:176 line references. The reconciler resolves those anchors against a current code index and marks note rot:

  1. Resolve each code_refs entry against the index (SCIP SQLite, codebase-memory-mcp SQLite, or Serena find_symbol).
  2. Missing symbol sets status: stale plus a symbol_missing callout. Symbol body hash changed since verified sets status: stale plus code_changed. Resolved sets verified: today.
  3. Run obsidian unresolved, orphans, deadends and write one hygiene note.
  4. A Stale notes.base view filtered on status == stale becomes the review queue.

It runs on the server as a SessionEnd hook or a systemd timer, because hooks run where Claude Code runs.

Why this scope and not the original one

The research found that only one file-to-knowledge edge exists anywhere in the current stack, and it is inert data in a dead database (claude-mem, disabled since 2026-03-15). A rename today invalidates zero notes. That gap is the entire problem, and it is a reconciliation job rather than a database feature.

The rest of the graph stack has existing answers: Serena for live symbols, Basic Memory for typed concept edges over the vault, codebase-memory-mcp for a committed cross-repo artifact. Building a graph database application competes with tools that are further along; building the reconciler competes with nothing.

What to drop if this is adopted

Current elementFate
grafeo 0.5.42 dependencyremove — SQLite suffices; see grafeo-feature-matrix
Graph database framing in ai-project-brainrewrite the MOC around the reconciler
graphtest rustc_driver HIR walker (paused 2026-03-10)do not revive — rust-analyzer scip supersedes it
Nested .git dirs from cargo newclean up regardless of the scope decision

The dependency lessons already recorded stay valid whatever is decided, since they are about cargo rather than about grafeo: cargo-workspace-dependency-inheritance, cargo-tree-verifying-deps-while-build-is-red, rust-path-vs-pathbuf-struct-field. chrono-already-in-tree-via-arrow is the exception — chrono arrived transitively through grafeo’s arrow-export, so removing grafeo would make chrono a genuine new dependency rather than a free one.

Graph View

Backlinks