Persistent Memory for Harnesses: Multi-Perspective Analysis

Persistent Memory for Harnesses: Multi-Perspective Analysis

HISTORICAL DOCUMENT: This analysis from 2026-01-30 explored memory integration strategies and recommended task-file consumers, .claude/rules/, and structured MEMORIES.md sections. The actual implementation (Memory System v3, 2026-01-31) implemented an append-only event store with auto-capture from checkpoints instead. See docs/index.md for the current implementation.

Generated by: /heavy (5 Opus agents, 3 rounds, adversarial dialogue + red-team) Date: 2026-01-30 Mode: Implementation (decision made: integrate memory techniques) Input: @rohit4verse "How to build an agent that never forgets" + Dhravya Shah Supermemory plugin

Executive Summary

Five Opus agents analyzed how persistent memory techniques can enhance the halt toolkit's harnesses (/melt, /heavy, /repair, /burndown). After 3 rounds of analysis -- including adversarial dialogue between First Principles (minimal) and AGI-Pilled (maximal), plus red-team stress testing -- the agents converged on a specific implementation that rejects most of the proposed infrastructure in favor of using Claude Code's native platform features plus one critical fix to existing code.

The core insight: The toolkit already captures structured session data (completion checkpoints, async task files). It already has a memory file (MEMORIES.md). It already has context injection hooks (read-docs-reminder.py). The problem is not missing infrastructure -- it's a broken pipeline. 27 async task files sit unprocessed because the consumer was never built.

Table of Contents

• Recommended Approach
• Implementation Tradeoffs
• Technical Details
• Execution Risks & Mitigations
• Structured Disagreements
• Dialogue Outcome
• Agent Perspectives Summary
• Next Steps

Recommended Approach

1. Build the Missing Task-File Consumer (Highest Impact)

The doc-updater-async.py hook already captures every git commit during autonomous sessions and creates structured JSON task files with commit message, diff, and instructions. 27 files have accumulated. Zero have been processed. The architecture is correct (producer-consumer queue) -- the consumer is missing.

Build a /remember slash command or SessionStart hook that:

• Reads pending .claude/async-tasks/*.json files
• Uses Claude (LLM intelligence) to distill them into curated MEMORIES.md entries
• Presents entries for developer confirmation before writing
• Archives processed task files

Why LLM curation matters: The red-team found that mechanical auto-append (commit message → MEMORIES.md) produces low-quality entries because hooks have no LLM access. Commit messages contain "what" but not "why." A Python hook that writes fix(hooks): macOS basename fix is less useful than an LLM that writes macOS ps returns full command path with parentheses -- use os.path.basename() on the result before comparison.

2. Create .claude/rules/ with Path-Scoped Rule Files

Use Claude Code's native path-scoped rules (YAML frontmatter with paths: globs) for domain-specific context:

Critical caveat from red-team: Task-spawned subagents (the 4 Lite Heavy planning agents in /melt) do NOT inherit .claude/rules/ context. The melt skill must embed essential rules directly in agent prompts. Path-scoped rules help the main execution agent, not the planning agents.

3. Enhance MEMORIES.md with Structured Sections

Process the 27 pending task files in a dedicated Claude session with developer oversight. Extract genuine learnings into structured sections:

• Architectural Decisions: Module split rationale, Lite Heavy 4-agent decision, subagent context isolation
• Error Gotchas: permissionDecisionReason display behavior, macOS basename, multi-session auto-approval collision
• Auto-entries (Hook System, Skills, General): One-liner bullets from feat/fix/refactor commits

Keep MEMORIES.md human/LLM-curated. Never auto-append mechanically.

4. Embed Memory-Relevant Context in Lite Heavy Agent Prompts

Since path-scoped rules are invisible to Task subagents, update the melt skill's Phase 0.5 (Lite Heavy planning) to:

• Read .claude/rules/ content and paste relevant portions into planning agent prompts
• Include user preferences and rejected approaches from MEMORIES.md
• Reference known error patterns when the task touches related files

Implementation Tradeoffs

Tradeoff 1: Direct MEMORIES.md Writes vs. Task-File Queue

Recommendation: Keep the task-file queue. Build the consumer. The existing architecture separates data capture (hook, fast, no LLM) from intelligent processing (agent, slow, LLM-powered). This separation is correct. Collapsing it loses quality.

Tradeoff 2: Platform-Native (.claude/rules/) vs. Custom Infrastructure

Recommendation: Use platform-native rules as the primary mechanism, but acknowledge the subagent limitation. Bridge the gap by having the melt skill read rules files and embed relevant content in planning agent prompts.

Tradeoff 3: How Much Memory Infrastructure

Recommendation: Moderate path. The minimal path ignores that the async pipeline is broken (27 unprocessed tasks). The maximal path builds infrastructure for a data volume that doesn't exist (31 lines after 136 commits). The moderate path fixes the actual broken pipeline and uses platform features for the rest.

Technical Details

Files to Create

Files to Modify

Files to Potentially Create (Phase 2)

Files to NOT Create

Execution Risks & Mitigations

Structured Disagreements

Disagreement 1: Is the Existing System "80% Done" or "Fundamentally Broken"?

Resolution: Both are partially right. The infrastructure (hooks, state files, injection) is ~80% there. But the pipeline is broken at a specific point: the consumer was never built. This is a targeted fix, not a new architecture.

Disagreement 2: Should MEMORIES.md Grow Automatically or Stay Manually Curated?

Resolution: The red team is right that mechanical auto-append degrades quality. But the consumer MUST be easy to invoke or it won't be used. A /remember command that processes pending tasks with Claude's help and asks for confirmation is the sweet spot: LLM quality + developer control + low friction.

Dialogue Outcome

Round 1.5: First Principles vs. AGI-Pilled on complexity level.

Convergence (both agents agreed on):

• Use platform-native features (.claude/CLAUDE.md, .claude/rules/, path-scoped YAML)
• No typed JSON stores, no confidence scoring, no vector stores
• The doc-updater-async pipeline is broken and needs fixing
• 28 hooks is already too many -- don't add more

Persistent disagreement: Whether fixing doc-updater-async requires code changes (AGI-Pilled: yes, the pipeline has 27 unprocessed tasks) or just a prompt edit (First Principles: edit the task prompt). The red-team resolved this: the task-file architecture is correct, the missing piece is a consumer.

New insight from dialogue: Error patterns in this codebase are thematic clusters (8 auto-approval fixes in 6 days), not exact duplicates. Git commit messages are unique but the underlying confusion is recurring. Memory entries should capture the theme ("auto-approval edge cases: session boundaries, directory scoping, permission types") not individual fixes.

Key evidence from First Principles: Claude Code natively supports a 5-tier memory hierarchy with path-scoped YAML frontmatter rules, @import syntax, and interactive # save command. The platform already solved "skill-aware injection" -- rebuilding it in Python hooks is duplicative.

Key evidence from AGI-Pilled: The doc-updater-async pipeline has 27 pending tasks with status "pending" and zero have ever been processed. The additionalContext output that suggests spawning a background agent is advisory only -- nothing forces execution. Editing the prompt of a pipeline that has never completed a task is insufficient.

Agent Perspectives Summary

Agent 1: First Principles (Elon Musk Algorithm)

Core argument: The system is 80% there. Most proposed memory techniques (vector stores, knowledge graphs, tiered retrieval, decay functions) solve problems that don't exist in a CLI tool with 200k context windows and full filesystem access. MEMORIES.md is 31 lines = 0.1% of context. There is no retrieval problem.

Key deletions: Vector stores, knowledge graphs, tiered/hybrid retrieval, decay scoring, confidence functions, typed JSON stores, 4-6 new hooks.

Key keeps: Checkpointing (already exists), write rules (most important), native CLAUDE.md + .claude/rules/ (platform features).

Proposal: 3 changes, zero new files. Edit doc-updater-async prompt, create .claude/rules/, add Error Gotchas section to MEMORIES.md.

Agent 2: AGI-Pilled (God-Tier Implementation)

Core argument: The 100th /build session should be dramatically better than the 1st. Error patterns compound, tooling commands should be remembered, planning insights should persist. The completion checkpoint data is being captured and thrown away.

Design: 4 memory stores (project-context, error-patterns, build-intel, preferences), 6 new hooks, confidence scoring with decay/reinforcement, skill-aware injection, token-budgeted retrieval.

After dialogue: Withdrew typed JSON stores, confidence scoring, 4-6 new hooks, custom retrieval. Conceded platform-native features cover most needs. Held firm on: doc-updater-async pipeline is broken, needs code fix not prompt edit.

Agent 3: Data Architect

Core argument: Storage schema must fit CLI constraints (no database server, no background processes). Three-layer model (Resources → Items → Categories) maps to JSONL + enhanced MEMORIES.md. Append-only JSONL avoids write conflicts.

Design: .claude/memory/items.jsonl (Layer 2) + .claude/memory/sessions/*.jsonl (Layer 1) + enhanced MEMORIES.md (Layer 3). Consolidation at SessionStart, rate-limited to 24h. Auto-managed sections in MEMORIES.md above manual section marker.

Key insight: Atomic file writes (temp file + rename) prevent corruption. Existing _state.py uses naive read-modify-write with no locking -- a risk for shared files.

Agent 4: Hooks Infrastructure Engineer

Core argument: Every memory concept maps to a specific hook event. The existing hook lifecycle (SessionStart → UserPromptSubmit → PreToolUse → PostToolUse → Stop) provides all the capture/injection points needed.

Design: 4 new hooks + 2 modifications. Single flat memory-store.json. Token-budgeted injection (400 SessionStart + 200 skill activation + 30 nudge = 630 tokens max). 5 mechanisms to prevent "wall of text": hard caps, aggressive selection, category filtering, confidence threshold, consolidation pruning.

Key insight: Integrate memory capture into stop-validator.py's success path rather than a separate Stop hook -- avoids ordering ambiguity and ensures capture only fires when stop is allowed.

Agent 5: DX Architect

Core argument: The developer experience transformation is "every session builds on everything before it." The MVP is literally "stop throwing away the completion checkpoint data."

Priority ranking by developer impact:

1. Error resolution memory (highest -- eliminates re-diagnosis)
2. Deployment topology caching (eliminates template placeholders)
3. Codebase pattern memory (eliminates re-exploration in Lite Heavy)
4. Build outcome memory (enables learning from iteration counts)
5. User preference memory (enables style matching)

Key insight: Session 1 → 10 → 100 progression: 22min → 14min → 8min. The compounding effect is not just speed -- it's elimination of wrong turns.

Red Team (Round 2)

Top 3 risks found:

1. Low-quality auto-append (risk score 72): Hook has no LLM access. Commit messages contain "what" not "why". MEMORIES.md becomes a changelog.
2. Path-scoped rules invisible to subagents (risk score 70): Lite Heavy planning agents are Task-spawned and don't inherit .claude/rules/. The most critical consumers of context are blind to it.
3. Replacing task-file queue is architectural regression (risk score 60): Current producer-consumer pattern is correct. The bug is the missing consumer, not the architecture.

The single most likely failure: MEMORIES.md becomes a low-quality auto-generated changelog and stops being useful. The fix: keep task files, build the missing LLM-powered consumer.

What We Learned from the Source Material

From @rohit4verse (Agent Memory Architecture)

Applicable to our system:

• Write rules -- what deserves remembering vs. noise. The most important technique. Without explicit rules, automated capture either remembers too little or too much.
• Memory is infrastructure, not a feature -- memory is a process (capture → store → retrieve → evolve), not a data dump.
• Memory must decay -- not everything should be remembered forever. Periodic pruning prevents confusion from stale data.

NOT applicable to our system:

• Vector stores / knowledge graphs -- our memory is 31 lines. No retrieval problem exists at this scale. Claude Code has 200k context and full filesystem access.
• 3-layer progressive compression -- designed for 10,000+ item stores. Our store has ~20 items.
• Embedding-based retrieval -- the "embeddings measure similarity, not truth" problem doesn't apply when the model reads the full memory file.
• Nightly/weekly/monthly cron jobs -- no background processes in a CLI tool.

From Dhravya Shah (Supermemory Plugin)

Applicable to our system:

• Context injection on session start -- we already do this via read-docs-reminder.py. The hook fires on both SessionStart and compaction.
• Automatic capture -- the doc-updater-async.py hook already captures commit data. The missing piece is the consumer.
• User profiles -- .claude/rules/ with path-scoped YAML frontmatter provides this natively.

NOT applicable to our system:

• External service dependency -- Supermemory requires a cloud service. Our system must work offline with zero external dependencies.
• MCP-based memory tools -- the skill system notes that MCP tools fire when Claude chooses to use them, not on every event. Hooks fire deterministically on events.

Next Steps

1. Now: Process the 27 pending async task files in a dedicated session. Extract genuine learnings into MEMORIES.md with structured sections. Delete the processed files.

2. Now: Create .claude/rules/ directory with the 4 path-scoped rule files. This is zero-risk, immediate benefit for the main execution agent.

3. Soon: Build a /remember slash command that processes pending task files with LLM curation. This closes the broken pipeline without adding hooks.

4. Soon: Update the melt skill's Phase 0.5 to read .claude/rules/ content and embed relevant portions in Lite Heavy agent prompts, bridging the subagent visibility gap.

5. Later: Monitor MEMORIES.md growth rate. If it approaches 200 lines, implement section archival. At the current rate (1 curated entry per ~20 commits), this is months away.