Ledger Memory System: Help AI Agents Reuse Experience and Stop Repeating Mistakes

Why Agents Need a "Ledger"

Download any open-source Agent framework today, configure Session, Context, and Memory, and it'll work just fine. So why bother building a separate "ledger memory system"?

After developing multiple AI agents over the past month, the author distilled one core pain point from hands-on experience: while existing Session/Context/Memory mechanisms work, they lack the ability to accumulate experience across sessions. When a conversation ends, all that valuable error analysis, post-mortem insights, and design decisions vanish along with the context. The next time the agent hits the same pitfall, it falls right in again.

The Ledger system was built specifically to solve this problem. Simply put, it's the agent's "logbook," "notebook," or "sticky note" — it crystallizes lessons from each session into behavioral rules, so every new session starts with that accumulated wisdom.

Worth noting: the author points out that this approach shares similarities with WikiSkill (an evolutionary system) proposed by Google researchers. Both aim to let agents continuously evolve and accumulate knowledge through use — but the author emphasizes that the ledger was independently designed and built, not copied from that work.

Session, Context, and Memory form the three-layer "memory" structure in mainstream Agent frameworks today: Session is the temporary context within a single conversation, Context is the information window injected into the model, and Memory is the short- or long-term storage interface provided by the framework. Their shared limitation is that they are fundamentally session-scoped — their lifecycle is tied to a single conversation. Once the conversation ends, information is either discarded or must be manually serialized and persisted by the developer. Even when frameworks offer a Long-term Memory option, the retrieval granularity and write timing are typically controlled by the framework, leaving developers little ability to fine-tune what's worth remembering, in what form, and when to inject it. This is precisely the gap the ledger system aims to fill by adding a layer above the framework.

What's Actually Stored in the Ledger

The author wrapped the ledger as a Skill and ported it to DeepSeek Harness. Users simply say "check the ledger" to trigger the skill and view its full contents.

In the actual demo, after just two or three days of use, the ledger had already accumulated quite rich content:

• 24 Iron Rules: The hardest-hitting entries — inviolable behavioral rules distilled from errors and post-mortems
• 2 Preferences: Records of the user's personal habits
• 18 Drafts: Information pending review or under observation
• 4 Consolidated Traces
• 14 Collected Entries

How Iron Rules Are Formed

The "Iron Rules" in the ledger aren't hard-coded by hand — they gradually evolve and naturally precipitate through actual use. The author shared several real examples:

• Safety rules like "code security, never expose code" and "prohibit log flooding during rendering"
• "Always restart after modifying packages or core code" — this one came from a real error. After modifying a core config file, the system threw an error. The agent caught it and immediately crystallized it as an Iron Rule.
• "Docs and code run on parallel tracks; treat running code as the source of truth, never guess" — this one is particularly interesting. During a post-mortem, the agent realized it had taken the long way around: it should have read the code directly to know how to make changes, but instead acted on guesswork. So it imposed this rule on itself.

This ability to "learn from mistakes and self-constrain" is the essence of the ledger memory system. It's somewhat like a constantly self-improving Wikipedia — every lesson is an entry.

Architecture: The Full Pipeline from Collection to Entry

From a technical architecture perspective, the ledger system can be broken down into several clear layers.

Storage Layer: Pure Document Infrastructure

At the bottom, the entire ledger is simply a pure document storage layer. All Iron Rules, preferences, drafts, and collected entries are essentially document-type storage. This infrastructure layer is simple, reliable, and guarantees excellent portability.

Collection Layer: Hooks + Manual Post-Mortems

How does data enter the ledger? There are two main paths:

1. Automatic collection: Tool errors are automatically captured via Hook mechanisms. Nearly all mainstream Agent frameworks today support registering hooks — this is the key to the ledger's cross-framework portability.
2. Manual post-mortems: Users can proactively issue instructions like "do a post-mortem on the last few tasks I ran," and the agent will analyze the underlying session data to identify what's worth preserving, then "log it."

The author particularly emphasizes the ledger's cross-framework portability: it has little dependency on the agent itself. As long as the agent exposes hook capabilities, everything else is handled through "contracts + tools." The LLM can invoke tools within this Skill to extract errors, post-mortem analyses, and summaries from the agent's existing Session, Context, and Memory — and store them independently in the ledger.

Hooks are event interception mechanisms provided by Agent frameworks, allowing developers to register callback functions at specific lifecycle points (e.g., before a tool call, after a tool error, when a task completes). In LangChain, for example, the CallbackHandler interface provides event hooks like on_tool_error and on_chain_end; AutoGen, CrewAI, and similar frameworks have comparable event bus designs. The ledger system leverages this universal mechanism to automatically capture error information when a tool call fails and trigger the "collect → analyze → log" pipeline — without invasively modifying the framework's core logic. This is why the author emphasizes that the ledger is cross-framework portable: as long as a framework exposes hook capabilities, the ledger can attach to it, fully decoupled from the specific orchestration engine.

Contract Mechanism: Mandatory Post-Task Summaries

The ledger system includes an important "contract" design: after completing a task, the agent is obligated by contract to generate a summary entry and place it in the ledger.

The author demonstrated this with a scenario: he asked the agent to modify a feature. After completing the task, the agent reported success. At that point, per the contract, the agent must organize its diagnostic findings and solution into a draft summary and store it in the ledger's "observation zone." The author's observation zone showed 18 drafts categorized into sections like "previous cleared entries," "analysis and investigation points," and "current session."

The Core Challenge: Injecting the Ledger into Agent Context

Once the ledger is built, if it just sits there quietly with no one knowing what's inside, its value is severely limited. The author articulates a core aspiration: make the ledger feel as natural to the agent as "common sense."

This leads to the most critical technical challenge of the ledger system — how to inject ledger content into the runtime context.

The problem is scale. The author poses a thought experiment: if a system runs for ten years, the ledger might accumulate hundreds of thousands or even hundreds of millions of entries — essentially a massive Wikipedia. Obviously, you can't dump all of that into a limited context window.

The author's solution is "drawer-style" layered injection:

• Segmented management through declarative mechanisms (similar to agent MD config files)
• Pulling only the relevant "drawers" of content into the context on demand, layer by layer
• The agent itself is equipped with a full suite of tool scripts, including commands for storage layer initialization, structured processing, observation, and pipeline management

A large language model's context window is the total amount of information it can "see" in a single inference pass — currently ranging from tens of thousands to millions of tokens across mainstream models. Despite expanding window sizes, injecting massive historical records in full still faces two practical bottlenecks: cost (token count directly impacts inference expenses) and the "Lost in the Middle" problem (research shows that models pay significantly less attention to information in the middle of the context than at the beginning or end, meaning too much information actually dilutes the weight of key content). Therefore, the core value of "drawer-style" layered injection is not just saving context space — it's ensuring that the most relevant experience entries appear where the model's attention is most concentrated through precise retrieval, so the ledger's "common sense" effect can actually be realized.

The Mental Model Limitations of Off-the-Shelf Agent Frameworks

The author also raises a thought-provoking point: off-the-shelf Agent frameworks lack sufficient "mental model" depth.

He acknowledges that in his fully self-built agent, he has fine-grained control over everything from system prompts and context planning to tool definitions and SOP workflows — essentially able to "point and shoot." But when porting the ledger Skill to an off-the-shelf framework like DeepSeek Harness, the lack of certain standardized processes and actions in the framework leads to a degraded result.

His practical advice: if you get hold of this ledger Skill, whether you're using Claude Code or Codex, don't register it as a Skill directly. Instead, let the model analyze and refine it first, then register it for use. This reminds us that the real-world effectiveness of infrastructure like memory systems is highly dependent on the controllability of the underlying Agent framework.

Summary: A Closed Loop of Collection → Storage → Crystallization → Injection

The ledger memory system is fundamentally about giving agents a long-term memory and self-evolution mechanism. It breaks free from the constraints of individual sessions, accumulating experience into documents through three pathways — Hook-based automatic collection, manual post-mortems, and contract-based summaries — and then delivers that "common sense" to the agent at critical moments through layered injection.

For anyone working on Agent development, the "collection → storage → crystallization → injection" closed-loop approach is more valuable to draw from than any single feature. It answers a fundamental question: how do you make an AI truly learn from experience, rather than starting from scratch every single time.