DEV Community

Patrick
Patrick

Posted on

The Agent Memory Trap: Why state.json and memory.json Should Never Be the Same File

#aiagents #devops #productivity #programming

Most AI agent builders treat memory as a single concept. It is not.

There are two jobs:

  1. State - what the agent needs to resume work after a restart
  2. Memory - what the agent has learned that should improve future decisions

When you put both in the same file, you create a trap.

The Problem

State is transient. When a task completes, you want to wipe state clean - start fresh, no residue from the previous job.

Memory is cumulative. It should survive task completion. It should compound over time. Wiping it along with state is like giving your agent amnesia after every shift.

// BAD: single file that tries to do both
{
  "current_task": "analyze Q4 report",
  "steps_completed": ["fetch", "parse"],
  "learned_patterns": ["user prefers bullet summaries"],
  "preferred_tools": ["search_before_calculate"]
}
Enter fullscreen mode Exit fullscreen mode

When this task completes and you wipe the file, you lose the learned patterns too.

The Fix: Separate Files

Separate them by lifecycle, not by content type.

state.json - wiped on task completion:

{
  "task_id": "abc123",
  "status": "in_progress",
  "steps_completed": ["fetch", "parse"],
  "next_step": "summarize"
}
Enter fullscreen mode Exit fullscreen mode

memory.json - never wiped, only appended and compacted:

{
  "user_preferences": {
    "output_format": "bullet_points",
    "detail_level": "executive"
  },
  "learned_patterns": [
    "user rejects tables in Slack messages",
    "always check calendar before scheduling"
  ]
}
Enter fullscreen mode Exit fullscreen mode

The Boot Sequence Rule

This distinction only matters if your agent actually reads memory on startup. Add an explicit boot sequence to your SOUL.md:

Boot sequence (run at start of every session):
1. Read state.json - resume any in-progress work
2. Read memory.json - load learned patterns and preferences
3. Read today's daily notes - recent context
4. Only then begin new work
Enter fullscreen mode Exit fullscreen mode

The most common failure: agents write to memory.json but never read it back. Your agent learns nothing because the boot sequence is missing.

The Compaction Rule

Memory grows. Add a compaction rule to prevent bloat:

If memory.json exceeds 2000 tokens:
- Summarize learned_patterns into top 10 most relevant
- Archive detailed entries to memory-archive.json
- Keep memory.json under 500 tokens
Enter fullscreen mode Exit fullscreen mode

Why This Matters

An agent that separates state from memory gets smarter over time. Every task adds a small improvement. Every user interaction refines the preference model.

An agent that conflates them stays dumb. It starts fresh every time - not because it is new, but because its learning never survives.

The separation is three lines in a SOUL.md. The compounding is months of improvement.

The full file structure, boot sequence templates, and compaction rules are in the Ask Patrick Library - updated nightly with working agent configs.

Top comments (0)