Curing Agent Amnesia: Dual-Axis Memory & Retirement

This is the second essay in the 【DSH Engineering Philosophy】series. In the first installment, Beyond Tool Use, I established the principle of delegating authoring while centralizing arbitration. Yet as developers hand increasingly complex codebases to agents, the hardest problem is rarely compilation—it is amnesia and repetition. A plan the whole team decisively rejected two weeks ago resurfaces verbatim in a fresh session, accompanied by a perfectly plausible explanation. This essay confronts that bottleneck head-on: how deepseek-harness encodes durable memory through a dual-axis decision-record system and a cryptographically frozen retirement mechanism.

Have you lived through this exact frustration?

In session A, you argued with your agent for half an hour and conclusively rejected a design with severe hidden pitfalls. Two weeks later, in a brand-new session, the agent faces a similar requirement—and resurrects the discarded plan verbatim, wrapped in a sincere and polished rationale.

Traditional engineering calls this a communication gap. But in an agent-led codebase, it is a systemic crisis: agents generate code at remarkable speed while possessing goldfish-grade persistence.

Some teams try to fight amnesia with ever-larger context windows or conversation summaries. Yet chat windows are transient beaches—waves wash everything away. What a codebase truly needs is a decision black box: versioned, reviewed, and mechanically defended.

I. First Principle: The Memory Bottleneck

At the heart of the deepseek-harness source repository lies its most foundational principle—P1, the Memory Bottleneck:

Code only encodes What. Teams genuinely lose Why and Why-Not. Any decision that lives only in a human mind, a chat thread, or a PR discussion evaporates the moment context rotates.

Code is a dry skeleton. It records what parameters a function accepts and what it returns—but never:

1. Why was approach A chosen over the more intuitive approach B?
2. What fatal flaw did B actually possess?
3. Under what future conditions should B be reconsidered (the resurrection clause)?

Once these answers vanish, whoever arrives next—a new hire or a fresh agent session—inevitably falls into the same trap. DeepSeek Harness does not rely on scattered issue threads; it generalizes the Architecture Decision Record (ADR) into an engineering carrier for every non-trivial change: the Agent Note.

II. Dual-Axis Paths: Encoding Labels Into the Filesystem

Documentation systems rot in one predictable way: tags drift from reality. A file's frontmatter proudly declares status: active while the body describes a superseded design; a checklist ticks boxes for code that was deleted months ago.

DSH's answer is radically mechanical—dual-axis paths: encode both classification dimensions directly into the filesystem path: {lifecycle}/{class}/yyyy-mm-dd-topic-title.md

1. Lifecycle axis

• proposed/ — a decision not yet implemented or still under review;
• implemented/ — the active, authoritative state, updated in the same PR as the code;
• rejected/ — decisively denied, kept forever to prevent re-litigation;
• archived/ — retired history, permanently sealed.

2. Class axis

Drawn from a closed set enforced by scripts/agent-note-tree.ts:

• feature: new user- or model-visible capabilities;
• bug-fix: defect repairs closing postmortems;
• architecture: structure, package boundaries, runtime contracts;
• process: toolchains, gates, packaging policy;
• testing: test strategies and quality suites;
• simplification: removal of surface area (refactors belong here, not a separate class).

Folder-as-Tag. Classification and status are the physical path itself—pseudo-state drifts become structurally impossible.

III. State Machine Transitions and the Alternatives Gate

Writing an Agent Note in DSH is not a stylistic exercise. Every active note must pass strict mechanical syntax and structure gates:

stateDiagram-v2
    [*] --> proposed: propose a change
    proposed --> rejected: verdict recorded
    proposed --> implemented: land + rewrite same commit
    implemented --> archived: sealed with content hash
    rejected --> [*]
    archived --> [*]

1. Transition is a rewrite

Moving from proposed/ to implemented/ is far more than git mv:

• verify-agent-note-format.ts rejects any future-tense proposal headings (## Proposal, ## Plan) inside an implemented note;
• the record must be rewritten as present-tense ## Decision, with acceptance criteria and risks folded into ## Consequences.

2. The Alternatives considered gate

Every decision record must contain an explicit ## Alternatives considered section; the gate script scans for its existence.

"A decision without recorded alternatives is an invitation to reopen the argument."

Each rejected candidate must explain why not, physically cutting off the path for an agent to resurrect it later.

IV. The Art of Retirement: Frozen Archives and Hash Seals

Many ADR libraries decay into landfills because they lack a retirement mechanism. As an agent-led codebase accumulates tens of thousands of commits, stale decisions pollute search results and confuse both humans and models.

DSH ships an industrial third state—archived/, permanent frozen retirement:

1. Strict criteria: only implemented notes may be archived. If a boundary concerns core security, persistent wire format, or a recurring defect trap, it must remain active forever.
2. Physical search isolation: .rgignore excludes archived/ from normal searches so stale facts never shadow current truth.
3. SHA-256 content sealing: verify-archived-agent-notes.ts computes a SHA-256 fingerprint over each archived triplet (English + Chinese + i18n config) and seals it into manifest.json. On every CI run, the gate proves existing seals are unbroken—even a single trailing-space change triggers a non-zero exit.

V. From Principle to Practice: A 10-Minute Fix

Do not be intimidated by the hundreds of notes in DSH. As a mid-level engineer pivoting to AI-assisted full-stack development, you can build your first memory line in ten minutes:

1. Create a minimal tree: .agents/notes/ with proposed/, implemented/, and rejected/.
2. Enact one rule: for every non-trivial change (interface changes, new dependencies, build-rule edits), commit a minimal note in the same commit with exactly two clauses:
   • Why: why this change is necessary;
   • Why Not: which alternatives were considered and discarded, and why.
3. Make notes mandatory input for agents: add one line to your AGENTS.md: "Before touching architecture or core logic, search .agents/notes/ for related decisions."

Let agents generate at full speed—let ADRs hold the memory. Only when every trade-off is physically anchored does AI-native engineering stop being a dangerous gamble on shifting sand.

🛠️ Practical Implementation: As an open-source engineering quality control meta-framework for AI Coding, PonyGo translates the dual-axis decision memory and retirement patterns explored here into an off-the-shelf CLI workflow. Through its standardized write-adr protocol and ponygo audit lifecycle gates, any modern codebase can adopt a DSH-grade decision black box out of the box. Reference: https://github.com/lanhui100/ponygo