The Memory Problem Is Continuity, Not Storage
ai-memory is a self-hosted memory and continuity layer for coding agents. The question here is not how to make an agent store one more note, but how to let work survive a change of session, tool, machine, or teammate without turning yesterday's context into unquestionable authority. Understanding that distinction gives you a practical model for judging the rest of the system: what it captures, what it turns into durable project knowledge, what it can retrieve, and what still must be checked against the current checkout.
The handoff that a note file cannot carry
Imagine an agent spends an afternoon investigating an authentication failure. It tries one approach, discovers that a tempting fix breaks session renewal, changes direction, and leaves two questions open. At the end of the day, the agent is gone. In the evening, another harness opens the same project. The repository is present, but the reasoning that makes the repository legible is not.
A note written inside the first agent's own memory system may not solve this. It may live only on one machine, be visible only to one agent, or be loaded only as a small project-local file. It may omit the failed approaches that explain why the obvious solution should not be repeated. It may also be difficult for a teammate to find. The problem is not that the fact “authentication is broken” was never written down. The problem is that the work has lost its continuity: where the investigation stopped, what evidence changed the plan, and what the next person should verify.
ai-memory is designed around that gap. Its subject is the relationship between coding-agent harnesses and a shared project memory service. A session in one harness can leave a typed handoff for a later session in another. Project knowledge can live on a server reachable from more than one machine. A team can share durable decisions while keeping an individual's pending baton private by default. The system therefore treats memory as coordination infrastructure, not as a private notebook attached to a single model.
The distinction matters even when both agents open the same directory. The checkout tells the second agent what the code looks like now; it does not tell them which hypothesis was already rejected, which test result changed the investigation, or which uncertainty was deliberately left open. A continuity layer has to carry the reasoning around the files without confusing that reasoning with the files themselves. That is why ai-memory connects a project identity and a handoff to the current checkout instead of trying to replace the checkout.
The same design becomes more useful when the project moves between machines. The memory can reside in a server on a laptop, a homelab, or another reachable host, while the agent still works in its local checkout. The server is not a magical shared context window: the next harness receives a bounded handoff or query result, and it can request more history when needed. The benefit is that the project does not depend on the particular agent process that happened to be running when the work stopped.
That distinction also explains why a handoff is not the same thing as a permanent note. A handoff is a baton for the next session: it says where the work ended, what remains open, and what should happen next. Durable project knowledge is meant to remain useful after that particular session disappears: a design decision, a recurring gotcha, or a procedure. Recall is the act of finding either kind of material when a later question needs it. These surfaces overlap, but they have different lifetimes and different failure costs.
A small but important model of memory
The project presents a compact loop: capture, consolidate, recall, and handoff. Each word names a different transformation.
Capture observes the work as it happens through lifecycle hooks. User prompts, tool boundaries, compaction events, and session boundaries can become bounded observations without requiring the agent to stop and perform a “remember this” ritual. Capture is deliberately not an unrestricted transcript archive. The server sanitizes incoming hook data at a typed boundary, and the client can exclude recognized file activity under private paths before it is spooled or sent over the network.
Consolidate turns a stream of observations into a more coherent account. At a true session end, ai-memory can create a rule-based summary page and a handoff even when no generative model is configured. An optional language model can later produce richer pages or split a session's durable lessons into concepts, decisions, and gotchas. This is closer to compiling evidence into a readable project record than to copying a chat log into storage.
Recall answers a later question from the resulting knowledge surface. The current design can combine full-text matches, named entities, links, graph neighbors, and optional vector similarity. That matters because a later question may use different words from the page that contains the answer. But relevance is not authority. A page that ranks highly is still historical evidence; it cannot grant permission to run a command, reveal a secret, or override the current code and instructions.
Handoff moves the immediate baton to the next session. A true session end records the summary and opens the handoff through a coordinated state transition. The next session can receive the newest eligible automatic handoff, or an explicitly created manual one can take precedence. Ownership matters on a shared server: a teammate should not accidentally consume another person's unfinished context unless the creator deliberately shares it or an authorized recovery path is used.
This four-part model prevents a common mistake. If capture, consolidation, recall, and handoff are all called “memory,” it becomes easy to ask one representation to do every job. Raw observations are useful evidence but noisy. A session handoff is timely but short-lived. A durable decision page is easier to retrieve and review but may become stale. A vector index can improve paraphrase recall but does not decide which page is canonical. The architecture works by keeping these roles connected without pretending they are identical.
It is useful to think of consolidation as a change in form, not a claim that the past has become certain. A raw observation preserves something about what happened during a session. A session summary gives that sequence a readable shape. A durable page extracts a relationship that may matter after the session: a decision and its reason, a failure and its remedy, or a procedure that should be repeated. Each step can lose detail, so the system keeps the underlying evidence and page history available rather than treating the summary as the only surviving account.
That is also why failed approaches belong in the story. If the second agent sees only “use session cookies,” they may repeat the investigation's first dead end. If they see that token rotation was tested, failed under a particular condition, and remains an open question, the old work becomes useful without becoming a command. Continuity is valuable precisely because it carries the path by which a conclusion was reached, not merely the conclusion's final wording.
Why the knowledge must remain visible
The durable center of ai-memory is a Markdown wiki backed by git. SQLite supplies search indexes, entity and link tables, session state, handoffs, audit records, and optional embeddings, but the Markdown pages remain the human-readable knowledge artifact. That choice makes the memory inspectable outside the agent: a person can open it, compare revisions, use ordinary text tools, or restore a page from history. It also makes the system portable in a way that a model prompt or opaque database export is not.
Visibility is not merely a convenience. It creates a review point between what happened and what a project should remember. A failed experiment can remain in a session record without becoming a permanent rule. A design decision can be written in a form a teammate can challenge. A newer page can supersede an older one without erasing the reasoning that led there. If a repository already has a canonical ADR directory, ai-memory advises keeping that directory authoritative and excluding it from capture rather than making a stale copy in the wiki.
This is why the project describes its database as derived even though SQLite is essential to operation. The index makes retrieval and lifecycle management fast and consistent; it is not supposed to become the only place where meaning exists. The split does have limits. Rebuilding indexes from Markdown does not recreate every session, observation, handoff, user, audit row, or embedding. The architecture gains inspectability by accepting a more explicit recovery model.
The visible wiki also gives people a way to disagree with the system. A page can be read before it is relied upon, compared with the current repository, or superseded by a newer version. That human checkpoint is important because an automated capture path sees activity, not significance. A command may have been run only as a smoke test. A temporary workaround may look like a rule. Keeping the durable form editable and versioned makes those distinctions recoverable instead of hiding them inside a model's private context.
The boundary that makes continuity trustworthy
A useful memory system must preserve enough of the past to prevent repeated work, but it must not quietly become a second source of truth for the present. ai-memory's own usage guidance draws that line clearly. Historical memory can explain why a design was chosen, what failed before, or which procedure was useful. Current source inspection, tests, and observed runtime behavior decide whether the design still works. Current project instruction files decide what an agent is authorized to do. The memory layer supports judgment; it does not replace it.
The same restraint appears in the system's scope. Pages belong to a workspace and project rather than to an unqualified path, and markers can make that identity explicit for monorepos, worktrees, or work/personal separation. A shared project wiki is intentionally shared knowledge, not per-page access control. The system can attribute writes and keep handoffs owner-scoped, but multi-user mode does not turn one data directory into separate tenants.
Nor does automatic capture mean perfect privacy. Path exclusions can remove recognized file-tool events before transport, which is a meaningful boundary. They are not complete data-loss prevention: shell commands, free-form patches, prompts, assistant text, aliases, and some ambiguous tool payloads remain outside that guarantee. The honest claim is layered protection with known coverage, not invisibility.
These boundaries shape ordinary use. Before proposing a redesign, an agent can search for an earlier decision and a related gotcha, then inspect the full page and compare it with the current code. Before sharing a server, an operator must decide whether every authenticated project member should see the same wiki and whether the transport is protected beyond the local machine. Before trusting an automatically generated rule, someone must be able to see what evidence produced it and whether the rule still matches present behavior. The system's value lies in making those checks easier, not in making them unnecessary.
That is the central judgment this series will develop. ai-memory is valuable when continuity itself is the expensive failure: when a person or team repeatedly loses the reasoning behind code changes, or when agents cannot carry a project safely across tools. Its design answers that problem by compiling bounded work into visible, versioned, retrievable knowledge and typed handoffs. The next question is how the system captures that work without turning every transient or private detail into a durable record.