The code shows what is currently implemented, but does not necessarily explain why such an architecture was chosen. The documentation may contain the reasons if they were recorded and kept up to date. The conversation history preserves more details, but along with them—incorrect hypotheses and outdated information.
Therefore, the task is not to make the agent read everything.
TAG140@@You need to choose the appropriate source and determine how much of the information obtained can be trusted.
Current project: documentation, specifications, and the code itself
Here, the critics of my initial approach have a strong argument.
A new developer does not begin work by reading the entire project history. They are given a map of the system, instructions, and a specific task. They study the other materials as needed.
It makes sense for an AI agent to act similarly.
In a small project, AGENTS.md or CLAUDE.md, up-to-date documentation, ADRs, work plans, and tests are often enough.
But Git is not a memory system in and of itself. It is version control: specifications, decisions, plans, and even session history can be stored in a repository.What matters more is the content and currency of these materials.
When there are too many source files
A separate problem is navigating a large codebase.
Aider Repo Map builds a compact map of the project structure while accounting for the token budget. The article “Codebase Intelligence for an Agent” examines the search and indexing of a Rails monolith with more than 3.5 million lines.
Structural navigation, relationships between symbols, and semantic search make it possible not to read hundreds of files for a single change.
However, even a perfectly located section of code does not necessarily explain the history behind the decision.
How not to trust outdated documentation
Suppose an architecture document states that two modules are independent, but a dependency has already appeared between them in the code.
An agent may read the document and propose a change based on outdated information.
OpenSpec and GitHub Spec Kit help organize work through requirements, specifications, and plans.
RouR describes GRACE and a doubled-graph in his article, comparing the stated architecture with the structure of the actual code.
Such a check can potentially reveal architectural discrepancies. But a graph match does not guarantee correct program behavior, and specifications and contracts require ongoing maintenance.
For a large project, this may be justified.For a small utility—to turn out to be redundant.
The main point here is not the choice of a particular methodology, but the principle: current knowledge is best verified against an independent source—the code, tests, or execution results.
Historical memory: Hansard and deja-vu
I’ll return to my own scenario.
The Claude Code lockout happened unexpectedly. Many solutions existed only in previous conversations. I had not managed to prepare a complete set of migration documents in advance.Hansard proved useful here. It allows you to search through saved sessions from different agents, access them via Recall, and continue working in another agent environment.An example from NetRuleRouterI’m currently continuing the development of NetRuleRouter—a program for routing traffic through different connections.While investigating the Windows TUN issue with error 5010, the agent reported:Hansard confirmed that TUF was a dedicated Windows laptop and that it had a local copy of the repository on it.After that, the agent indicated the need to inspect the logs and the lifecycle of TUN/routes before changing the code. Details about the test laptop and the conditions for reproducing the error do not necessarily belong in the architectural documentation. However, they can be useful during diagnostics.
At the same time, I cannot yet claim that Hansard accelerated the correction of the error.
To draw such a conclusion, one needs to examine the Recall query itself, the sources found, and the influence of the information on subsequent actions.
This episode demonstrates the potential benefit of historical context, but is not yet a measurement of the tool’s effectiveness.
What makes deja-vu interesting
Another project is deja-vu by VShulcz. It indexes local coding-agent logs and provides search through CLI, MCP, and other integrations.
The development-oriented features are particularly interesting:
deja wip — recovering unfinished work;
TAG218@@
deja blame — finding historical sessions related to files;
TAG222@@deja fix — finding prior actions after similar errors;
TAG226@@decision statuses, including rejected ones;
TAG230@@warnings about files being changed after a discussion is found.
TAG234@@The latter capabilities help not only find old recommendations but also assess how applicable they still are. For example, if the fix found relates to a module that was later rewritten, that is a reason to double-check the search result. And the absence of the error recurring in the old log does not yet prove that it was the action found that fixed it.
I haven’t tested deja-vu itself yet. Hansard already meets my current need, so I don’t intend to install a second indexer just to look it over.
When history helps specifications
An interesting detail: the deja-vu session recall extension has already been included in the GitHub Spec Kit community catalog.His submission was closed on November 5, 2026.
The extension uses the current spec.md and plan.md to search through previous sessions: what was tried before, which decisions were rejected, and which files were changed.
However, inclusion in the community catalog does not mean that the Spec Kit maintainers have reviewed or approved the quality of the extension’s code. The catalog confirms the correctness of the entry’s formatting, not the results of an independent audit. Still, the mechanism itself is interesting.
The specification defines the current task, while the archive helps prevent repeating experiments that have already been conducted.
Here, history and documentation do not compete but complement each other.
Transferring unfinished work and coordinating agents
Now consider a different scenario. Claude Code fixes a bug, runs commands, and modifies files. At this point, the limit runs out. You can ask it in advance to prepare HANDOFF.md, but if the work has already been interrupted, this option may not be available.
For situations like this, baton was developed, as described in the article “Transferring Sessions Between Console AI Agents Without Losing Context.” It reads existing logs, prepares materials for continuing the work, and can transfer local changes between computers.
Hansard also supports continuing work in another agent. Therefore, such solutions should be compared not by whether they have a “Continue” feature, but by what data is actually transferred: message history, tool results, changed files, the work plan, and source references. At the same time, a saved log is not equivalent to transferring the model’s internal state.Thinking blocks, caching features, and the protocols of different providers do not guarantee identical continuation of reasoning.
Orchestrators also have another mechanism. For example, LangGraph separates execution checkpoints from long-term knowledge stores. A checkpoint allows a process to resume from a known state. Historical memory helps restore past experience. A single product may use both approaches.
When there are multiple workers
In the comments, anikin-v described his own practice: task working folders containing plans, hypotheses, and intermediate results. The agent updates them itself or on command.
Another particularly interesting part of his experience involves long-running tasks. For these, he sometimes uses a separate controller agent that does not write code. It monitors the plan, prepares assignments for the workers, records results, and organizes the handoff of work. Essentially, this creates a small virtual team.
Beads and SpecWithCode address similar problems, as aabyzov described.
Another example is the multi-agent OpenIDE, which allows users to create separate discussion branches, assign tasks to different agents, and return review results to the main conversation.
Here, it is important not merely to store memory, butto manage context flows between workers.
However, structured handoff does not rule out errors either.A controller may misinterpret a report, while a summary may lose an important detail.
Automatic memory: writing it down does not mean remembering
Between a full archive and manually maintained documents, there are systems for automatic knowledge extraction.
Claude-Mem, kaeru, and skillmem use different mechanisms for storing observations, decisions, and reusable techniques.
But two problems arise here: when to consult memory and how to determine the reliability of what is found.
The cost of unused memory
In the article “Writing It Down Does Not Mean Remembering,” the author described an experiment with MemShelf. On the 38th day of the system’s operation, the index and digests of 157 stored episodes occupied about 36.6 thousand tokens—18.3% of a 200-thousand-token window.
In another segment covering 30 separately analyzed days, the author found no calls to the MemShelf and DocShelf MCP tools. At the same time, he accessed the archive manually.
These measurements cannot be directly combined into a single effectiveness statistic. And the absence of MCP calls does not prove that all memory is useless: the information could have entered the context in other ways.
However, the problem is readily apparent. Continuously loaded memory can occupy a significant portion of the window without providing corresponding value through retrieval.
The developers of kaeru faced a similar question. They examined more than 13 thousand log files; in one small observation, agents across seven sessions never once used an optional prompt to read the stored reasoning.
Seven sessions are too few to draw broad statistical conclusions, but the problem itself is clear.An agent may have access to memory without ever accessing it. Or, conversely, the system may inject history too frequently, wasting tokens and polluting the working context.
MCP provides an invocation interface. Hooks, instructions, and skills can control when memory is accessed. But none of these mechanisms alone guarantees the relevance of the result.
The context window also needs to be managed
In its article “Effective context engineering for AI agents,” Anthropic discusses history compression, pruning tool results, selective file reading, and isolating subagent work.
This is not the same as long-term memory. Compression frees up space but may lose details. Pruning command results reduces the context size but may sometimes require repeated calls. Subagents make it possible not to carry all intermediate reasoning into the main session.
Therefore, increasing the context window does not, by itself, solve the problem of knowledge management.
What if memory has preserved an error?
Suppose an agent reaches an incorrect conclusion and records it as useful experience. Later, another agent retrieves this record and treats it as a confirmed decision. Errors accumulate.
Therefore, it is useful to store not only the content of a record but also its source, date, status, validation conditions, and relationship to the current code.
It is especially important to distinguish hypotheses, confirmed results, overturned decisions, and information of unknown reliability.
There is also the question of security. An old conversation may contain instructions that once related to a different task or were obtained from an untrusted source.If an agent begins executing them while reading the archive, historical memory turns into a channel for transmitting unwanted commands.
Therefore, the conversations found must be treated as data about the past, rather than as new instructions to execute.
From historical discussion to a verified solution
After becoming familiar with the different tools, I formulated a simple workflow for myself.
Suppose an agent has found an old discussion about fixing a TUN bug. It is risky to apply the solution found immediately. First, the source and date of the discussion must be established. Then, determine whether it was a hypothesis, a confirmed result, or a rejected option.
After that, cross-check what was found against the current code, documentation, and tests. And only after verification should the solution be used or rejected. If something important has been established, the result should be recorded in the current work plan, ADR, or KB. This gives the following sequence:
Find → determine the status → check whether it is still current → apply and verify → record the result.
The lifecycle of knowledge: historical information is screened and verified before it influences the work and is incorporated into current documentation. 
