Skip to content

v1.1.0 ·

The framework that forgot everything: a local knowledge graph

The problem

AIDLC has no working memory of the codebase it operates on. Whenever the framework needs to understand the code — in any lifecycle phase — it re-explores from scratch: re-reading directories, re-inferring architecture, re-discovering conventions and technical debt. And when the framework modifies the code (implementation, maintenance), the understanding it gained evaporates at session end.

The local knowledge graph is AIDLC's own read/write memory of the codebase:

  • Read before acting — when a phase needs to understand the code, it queries the graph first instead of re-exploring.
  • Write after modifying — when a phase changes the code, it updates the graph immediately after (new/changed modules, decisions taken, debt introduced or paid down).

This keeps the graph current with the codebase as the lifecycle runs — a living memory, not a one-shot discovery snapshot.

How it could be solved

The architecture was not really in doubt — YAML as the source of truth, with a derived query index over it. The open decision was the index storage engine, and all three candidates had a real cost.

Option A — YAML plus a better-sqlite3 index

Fastest queries, FTS5 full-text search for free, WAL concurrency, and proven far beyond our scale. The cost is that it would be the first native dependency in the CLI: prebuilt-binary and gyp failures on some platforms, larger installs, and a CI matrix across three operating systems and several Node versions. Medium risk, and operational rather than technical.

Option B — YAML plus an in-memory index, no SQLite

Zero new runtime dependencies. The index gets built by parsing YAML at command start, and about a thousand entities parses comfortably inside a 100ms query budget; search via a simple tokenized inverted index, graph traversal in plain JavaScript. The index is a derived cache by design, so persisting it is an optimization rather than a requirement. The costs are re-parsing on every invocation and DIY relevance ranking that is cruder than FTS5. Low risk — if benchmarks failed, the storage interface swaps.

Option C — YAML plus node:sqlite from the standard library

Real SQLite and FTS5 with no native build step. The cost is raising the engine floor to Node 22, which is a breaking change for existing CLI users.

Chosen: Option C. Real SQLite and FTS5 with zero npm dependencies, paid for by raising the CLI's Node floor from 18 to 22 — a breaking change that needed a major version bump and an explicit call-out in the release notes and README. The writer, reader, and context generator all sit behind a narrow index interface, so the engine stays swappable if that trade ever looks wrong.

How AIDLC solves it

  • @rasensio/aidlc@1.1.0 and @rasensio/aidlc-content@1.1.0 on npm (public), latest dist-tag.
  • Git: merge commit ba3f0d7 on main, release commit 4a61e2b, tag v1.1.0, pushed to GitHub.
  • GitHub release v1.1.0 with the R12.3 breaking-change callout (Node ≥22.13, nvm install 22, no other migration) — notes added post-hoc since the release script only auto-generates a changelog link.
  • Website: deploys via Vercel from the main push (updated CLI reference included).