1707 Analysis Persistent Memory For Harnesses 07c45c53

# 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](index.md#memory-system-v3) 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](#recommended-approach)
- [Implementation Tradeoffs](#implementation-tradeoffs)
- [Technical Details](#technical-details)
- [Execution Risks & Mitigations](#execution-risks--mitigations)
- [Structured Disagreements](#structured-disagreements)
- [Dialogue Outcome](#dialogue-outcome)
- [Agent Perspectives Summary](#agent-perspectives-summary)
- [Next Steps](#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:

| File | Scope | Content |
|------|-------|---------|
| `hooks.md` | `config/hooks/**` | Hook architecture, error gotchas (permissionDecisionReason, macOS basename, multi-session collisions), patterns (is_autonomous_mode_active, log_debug) |
| `skills.md` | `config/skills/**` | Skill architecture, subagent isolation constraint, Lite Heavy 4-agent requirement, stop-hook checkpoint schema |
| `testing.md` | `config/skills/harness-test/**` | Sandbox workflow, CWD propagation requirement |
| `general.md` | (no path scope) | Source of truth, commit conventions, hook count warning, state file discipline |

**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

| Direct Write (First Principles) | Task-File Queue + Consumer (Red Team) |
|--------------------------------|--------------------------------------|
| Simpler: ~20 lines of Python changes | More complex: need a consumer (slash command or hook) |
| Immediate: entry appears after commit | Deferred: entries batch-process at session start or on command |
| No LLM: mechanical commit→entry extraction | LLM-curated: intelligent distillation of what/why |
| Risk: MEMORIES.md becomes a changelog | Preserves curation quality |
| Risk: race conditions on shared file | Task files are per-commit, no races |

**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

| Platform-Native | Custom Hooks (AGI-Pilled original) |
|----------------|-----------------------------------|
| Zero new Python code | 4-6 new hooks, shared `_memory.py` module |
| Path-scoped auto-loading | Skill-aware injection via hook logic |
| **Invisible to Task subagents** | Could embed in subagent prompts |
| Maintenance: Anthropic maintains the platform | Maintenance: 28→32+ hooks, all team-maintained |

**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

| Minimal (First Principles) | Moderate (Converged) | Maximal (AGI-Pilled original) |
|---------------------------|---------------------|------------------------------|
| 0 new hooks | 0-1 new hooks | 4-6 new hooks |
| 3-4 markdown files | 5-6 markdown files + consumer | 6+ JSON stores + shared module |
| Extend existing prompt | Build task consumer | Full capture/inject/decay pipeline |
| Works now | Works in ~1 session | Works in ~1 week |

**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

| File | Purpose |
|------|---------|
| `.claude/rules/hooks.md` | Path-scoped rules for hook development (architecture, gotchas, patterns) |
| `.claude/rules/skills.md` | Path-scoped rules for skill development (architecture, constraints) |
| `.claude/rules/testing.md` | Path-scoped rules for harness testing |
| `.claude/rules/general.md` | Global rules (source of truth, conventions, discipline) |

### Files to Modify

| File | Change |
|------|--------|
| `.claude/MEMORIES.md` | Add structured sections (Error Gotchas, auto-entry sections). Process 27 pending tasks with LLM curation. |
| `config/skills/melt/SKILL.md` | Phase 0.5: Read `.claude/rules/` content and embed in Lite Heavy agent prompts. Reference MEMORIES.md for rejected approaches. |

### Files to Potentially Create (Phase 2)

| File | Purpose |
|------|---------|
| `config/skills/remember/SKILL.md` | `/remember` command that processes pending async task files into curated MEMORIES.md entries |
| OR `config/hooks/memory-consumer.py` | SessionStart hook that processes pending task files (alternative to `/remember` command) |

### Files to NOT Create

| Rejected | Reason |
|----------|--------|
| Typed JSON stores (error-patterns.json, build-intel.json, etc.) | Data volume is 31 lines after 136 commits. No retrieval problem exists at this scale. |
| `_memory.py` shared module | No new memory-specific infrastructure needed. |
| Confidence scoring / decay functions | Codebase facts are binary true/false. A bug fix doesn't become 90% true after 2 weeks. |
| Vector store / knowledge graph | The file system IS the knowledge graph. Grep + Read + 200k context = no retrieval problem. |
| New capture/injection hooks | 28 hooks already exist. Recent git history is dominated by fixing them. Each new hook is a liability. |

---

## Execution Risks & Mitigations

| Risk | Likelihood | Severity | Mitigation |
|------|-----------|----------|------------|
| **MEMORIES.md auto-append degrades quality** | 9/10 | 8/10 | Use LLM-curated consumer, never mechanical append |
| **Path-scoped rules invisible to Lite Heavy agents** | 10/10 | 7/10 | Build skill reads rules and embeds in agent prompts |
| **Race conditions on MEMORIES.md** | 6/10 | 7/10 | Task-file queue (one file per commit) avoids shared-file mutation |
| **Cross-project hook pollution** | 8/10 | 5/10 | Only write to MEMORIES.md if file already exists with expected structure |
| **Unbounded MEMORIES.md growth** | 7/10 | 6/10 | LLM curation acts as quality gate; periodic manual pruning of entries >30 days |
| **Hook timeout corrupts MEMORIES.md** | 3/10 | 8/10 | Don't write to MEMORIES.md from time-constrained hooks. Use task-file queue. |

---

## Structured Disagreements

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

| First Principles | AGI-Pilled |
|-----------------|------------|
| 80% done. MEMORIES.md + checkpoints + hooks already exist. Need 3-4 markdown files. | Fundamentally incomplete. Structured data is captured and thrown away. No compounding across sessions. |
| Evidence: 31 lines, 136 commits, existing hooks handle injection | Evidence: 27 unprocessed tasks, completion checkpoints discarded, zero error patterns retained |

**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?

| Auto-append (implementation plan) | Curated-only (red team) |
|----------------------------------|------------------------|
| Every worthy commit gets a one-liner. Compound automatically. | Only LLM-distilled insights enter. Quality over quantity. |
| Risk: becomes a changelog | Risk: consumer never runs (same failure mode as today) |

**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.