Memory Files & Persistent State

Introduction

Session context is ephemeral — it dies when the session ends. Persistent state is what survives between sessions and makes every new session smarter than the last. Knox's stack has four distinct persistent state mechanisms, each engineered for a different type of information.

The most important rule governing all of them: the one-fact-per-file rule. It is the principle that separates a maintainable memory system from a sprawling monolith that contradicts itself.

The Four Memory File Types

MEMORY.md: The Auto-Index

~/.claude/projects/<hash>/memory/MEMORY.md is the file Claude Code auto-manages. It persists across all sessions in this project context, and Claude Code reads it automatically at the start of every session.

The key discipline: MEMORY.md is an index, not a document. Each entry is one line pointing to a topic file:

## About Knox (see also: SOUL.md)
- **Jeremy Knox** — Engineering Manager at SAS, 16+ years

## Behavioral Feedback (CC Insights)
- [Chart first, memory second](feedback_chart_first_memory_second.md)
- [Session start protocol](feedback_session_start_protocol.md) — Semantic Memory Layer pre-context first
- [Post-PR retro is mandatory](feedback_post_pr_retro.md) — retro → lessons → memory_remember

Each bracketed link points to a topic file that contains the full fact. When the fact changes (e.g., the session-start protocol evolves), only the topic file changes. MEMORY.md's index line stays the same.

When MEMORY.md exceeds 200 lines, the load warning appears. This is the signal to compact: move inline blocks to topic files, reduce index entries to one-line summaries. MEMORY.md must load on every session — it cannot grow without bound.

lessons.md: The Compound Learning Log

Each project has a lessons.md in its root. This is the anti-pattern register: what went wrong, why, and the rule that prevents recurrence.

The format is not optional:

## 2026-05-17 — Phemex Unit Semantics
**Mistake**: Bot sent qty=1 as "1 contract"; Phemex read as 1 BTC
**Root cause**: Cutover to v4 API changed unit semantics without flagging
**Rule**: $1 live round-trip before any "live" declaration on a new API version

Three fields. Always in order: mistake → root cause → rule. The date prefix enables freshness assessment. The category enables pattern detection.

When the same category appears three or more times in lessons.md, the rule is not strong enough. Escalate it: move the rule from lessons.md to CLAUDE.md Tier 1. This is the compound learning loop working correctly — repeated failures escalate to harder constraints.

Daily Log Files: The Operational Record

~/.config/agent/workspace/memory/YYYY-MM-DD.md holds Agent Gateway's daily operational log. Each day gets one file. What was built, what failed, what decisions were made, what hasn't been tried.

These files are not loaded into every session. They are Tier 3 — fetched by specific skills:

• /morning-brief skill queries the last 3–7 daily logs
• /rca skill queries logs around the incident date
• /weekly-retro queries the last 7 daily logs

Storing these as individual dated files makes retrieval surgical: query 2026-05-17.md specifically rather than scanning a monolithic log file.

Topic Files: The One-Fact-Per-File Implementation

~/.claude/projects/<hash>/memory/*.md contains the actual fact content that MEMORY.md indexes. Each file covers exactly one topic.

Examples from Knox's stack:

• feedback_session_start_protocol.md — the complete session-start-protocol behavior expectation
• reference_memory_service_split_brain.md — detailed account of the split-brain incident
• project_invictus_v4_shipped.md — the trading bot v4 launch context and current state
• feedback_phemex_unit_semantics_missed_cutover.md — the Phemex unit semantics lesson in full

When the Semantic Memory Layer chunk count changes (now 2,968), only reference_memory_service_chunk_count.md needs updating. MEMORY.md's index line stays the same.

The Compound Learning Loop

The five-step loop that makes each session smarter:

1. Observe — Something notable happens: a correction, a failure, a discovered pattern
2. Extract — /learn skill or manual: classify as pattern, anti-pattern, or convention
3. Store — memory_remember() to Semantic Memory Layer + lessons.md entry + MEMORY.md index update (if MEMORY.md-worthy)
4. Retrieve — memory_query at next session start surfaces the stored lesson
5. Apply — Agent reads the lesson, applies the convention, avoids the anti-pattern

The loop is not self-executing — it requires discipline. Knox's behavioral feedback list in MEMORY.md (the CC Insights section) grew from consistently running /learn after corrections and running memory_remember after each PR retro.

A correction that isn't stored is a tuition payment with no graduation. The lesson exists in the session memory — but sessions end. Only stored lessons persist.

Frontmatter for Traceability

Topic files that need explicit lifecycle tracking use frontmatter:

---
date: 2026-05-17
category: trading
status: active
project: the trading bot
---
# Phemex Unit Semantics

...

The status: active vs status: archived field is the mechanism for the pruning lifecycle (covered in the “Pruning & Compaction” lesson). When a fact is superseded, the topic file gets status: archived — not deleted — so the decision history is preserved while the active index removes it.

Practical Application: Setting Up Your Memory System

For a new project:

1. Create lessons.md at the repo root with the format header
2. After every correction from your operator (or every session where you discover a footgun), add an entry
3. After every PR retro, run memory_remember with the session summary
4. When MEMORY.md grows past 200 lines, compact: move inline blocks to topic files

For an existing project with a messy MEMORY.md:

1. Read MEMORY.md and identify every multi-line inline block
2. For each block: create a topic file, replace the block with a one-line index entry
3. Run /learn on the session to capture any new patterns discovered during the cleanup
4. Verify no orphaned links remain

The payoff: six months of disciplined lessons.md entries creates a lessons library that surfaces recurring failure patterns, prompts escalation of chronic issues, and prevents repeat mistakes across every agent that works on the project.

Summary

• MEMORY.md is an auto-managed index — one line per fact, linking to topic files
• lessons.md is the anti-pattern register — three fields, always: mistake → root cause → rule
• Topic files implement one-fact-per-file — surgical updates when facts change
• The compound learning loop: observe → extract → store → retrieve → apply
• Recurring category (3+ entries) triggers escalation from lessons.md to CLAUDE.md Tier 1
• Frontmatter (status: active/archived) is the mechanism for fact lifecycle management

What's Next

The next lesson goes deep on the semantic memory layer — Semantic Memory Layer, the query-first habit, how embeddings differ from structured recall, and what a production knowledge OS looks like when maintained over months of real sessions.