A Governed Memory Layer for Coding Agents

The shortest accurate definition of ai-memory is this: it is a self-hosted, file-first continuity layer that turns bounded coding-agent activity into inspectable project knowledge and typed handoffs. Its value is not that it stores everything, nor that a model can write fluent summaries. Its value is that work can cross a session or harness boundary while remaining versioned, searchable, scoped, and subject to current-code verification. The practical decision is therefore not whether to enable “memory” in the abstract, but which continuity layer the workflow needs and which boundaries the operator is willing to maintain.

Continuity as a governed compilation process

The architecture is easiest to judge as a chain of transformations. A hook observes a bounded event and passes it through a sanitizer. A session end can turn accumulated observations into a rule-based summary and a handoff. Consolidation can compile selected evidence into a Markdown page. SQLite indexes those pages and operational records so later queries can combine text, entities, links, graph neighbors, and optional vectors. A receiving agent gets a bounded baton or a search result, then checks the current checkout before treating the history as applicable.

Each transformation answers a different problem. Capture prevents the person from having to remember every useful detail manually. The session account preserves chronology. The handoff reduces immediate restart cost. The Markdown page carries semantic knowledge beyond one run. The SQLite index makes the knowledge findable. Scope and actor ownership keep it from landing in the wrong project or being consumed by the wrong operator. Retention and supersession prevent the active corpus from becoming an undifferentiated archive.

That chain also explains why the file-first choice is central rather than cosmetic. A page can be opened, reviewed, versioned, corrected, exported, or deliberately excluded when another repository artifact owns the decision. SQLite can be rebuilt for page and link search, but it also contains operational state that needs its own backup. The split is an explicit trade: human visibility and portability are worth the extra recovery discipline, because an opaque database or hidden prompt would make the meaning of continuity harder to inspect.

The result is not a new authority layer above the repository. ai-memory remembers why a choice was made, what failed, which handoff remains open, or which procedure previously worked. The current checkout, current instruction files, tests, compiler, and observed runtime decide what is true and permitted now. A high-ranking page can change what an agent investigates first. It cannot authorize a command, disclose a secret, grant a permission, or override current instructions.

Choose the smallest continuity layer that solves the problem

For many individual workflows, the basic hook-and-wiki path is enough. If the recurring failure is “I stopped one agent and forgot where I left off,” automatic capture, a rule-based session summary, and an owner-aware handoff address the problem without requiring a native transcript bridge. The next agent can receive a bounded baton and search the project wiki when it needs more context. This path has fewer moving parts and remains useful without a generative provider.

Managed workstreams justify their additional complexity when native session continuity matters. ai-memory run can resume a harness's own session where supported, read visible native history without rewriting the private store, and carry a bounded unseen ledger delta into another harness. That is valuable when a user needs more than “what was the summary?”—for example, when preserving visible tool history or returning to a native session picker matters. It is not a universal upgrade.