Make Memory Addressable Before It Is Large
Long-running agents fail less from forgetting everything than from remembering the wrong slice at the wrong time. Treat project memory as an API, not a notebook. The root file, whether `AGENTS.md`, `CLAUDE.md`, or `soul.md`, should be a router: conventions, lookup paths, and pointers to deeper files. It should not contain the history of the project. Once that file becomes a compressed biography, every run starts with stale claims and wasted tokens.
Use an OKF-style bundle layout for the actual knowledge. Each bundle gets predictable metadata, at minimum `type`, and preferably `title`, `tags`, owners, related concepts, and freshness fields. Put an `index.md` at the bundle root and at each major subsection. The index is not prose documentation; it is a navigation table: concept IDs, summaries, dependencies, last updated dates, and read-this-when hints. That lets an agent progressively disclose context: root index, section index, one or two target docs, then code or logs.
The failure mode is a beautiful vault that only a human can browse. Avoid ambiguous filenames like `notes-final-2.md` and avoid dumping transcripts into `wiki/`. Use stable concept IDs such as `auth.session-refresh`, `billing.stripe-webhook-replay`, or `frontend.table-density`. The agent should be able to request `bundle=product, concept=billing.stripe-webhook-replay` without scanning the whole tree.
Separate Knowledge From State
Once memory is addressable, split durable knowledge from run-specific state. A useful project vault usually has four lanes: synthesized wiki pages, run logs, gotchas, and state tables. Wiki pages explain how the system is supposed to work. Run logs record what happened. Gotchas encode sharp constraints discovered through failure. State tables preserve resumable facts that should survive compaction, crashes, and overnight execution.
State tables are the underrated layer. For a long autonomous loop, keep machine-readable markdown tables or small JSON/YAML files for `tasks`, `decisions`, `artifacts`, `verification`, and `open_questions`. Each row needs an ID, status, evidence pointer, timestamp, and next action. A resumed agent should not infer progress from a chat transcript; it should read `state/tasks.md`, inspect evidence paths, and continue from the next unblocked row.
Keep gotchas aggressively curated. Large skill libraries and comprehensive docs often degrade performance because they force the model to average over too much. A gotcha file should contain only constraints that have caused real failures or are expensive to rediscover: “Playwright must run with video enabled for checkout changes,” “Never mix client A and client B fixtures,” “Snapshot tests pass locally but fail in CI unless timezone is UTC.” If a note is merely descriptive, move it to the wiki. If it changes behavior under pressure, keep it in gotchas.
Turn Runs Into Training Data For The Harness
With knowledge and state separated, the loop can use memory as feedback rather than storage. Every autonomous run should emit a compact log with trigger, goal, selected memory, plan, commands, outputs, artifacts, verification evidence, failures, cost, and final status. The log is not for sentiment analysis later. It is the raw material for a retrospective pass that updates the memory system after the work is done.
Make retrospectives narrow and evidence-based. The retrospective agent should compare intended outcome, state table transitions, verification artifacts, and command logs. Its job is to propose small patches: add one gotcha, update one index entry, change one skill step, mark one stale doc, or record one new decision. Do not let it rewrite the whole vault after every run. Automated memory updates need the same discipline as code changes: scoped diffs, reviewable evidence, and rollback paths.
This is where failed sessions become useful. If the agent wasted 40 minutes retrying a bad test command, the fix is not “be more careful.” Add the exact failure signature to gotchas, patch the relevant skill, or install a deterministic hook that rejects the bad command before execution. Treat repeated agent mistakes as harness bugs. Natural language reminders are acceptable for judgment-heavy work, but objective gates belong in code or scripts.
Route Context, Models, And Parallelism Deliberately
After the memory system can teach the loop, optimize how agents consume it. Different phases need different context and sometimes different models. Planning may need broad indexes, recent decisions, and unresolved questions. Implementation needs local gotchas, relevant code, and task rows. Verification needs the definition of done, artifact paths, and prior failure signatures. Review needs the diff, evidence, and run log, not the entire project archive.
Use model routing around those phases. A stronger planning model can interview the user or inspect the repo to extract project-specific judgment into markdown. A leaner execution model can operate from indexed tasks and gotchas. A reviewer model can be forced into binary pass/fail, score, or patch-required output. For research-heavy or document-heavy phases, use the agent that handles retrieval and structured citations best. For implementation and shipping, use the one that burns fewer output tokens and has better worktree discipline. Keep prompts, skills, and repo conventions portable so swapping agents does not require rewriting the operating system.
Parallelism should follow bundle boundaries, not enthusiasm. Subagents can refactor a large wiki into OKF by section, audit independent skills, or verify separate subsystems. They should share the same spec and write to separate output files, then a coordinator merges indexes and resolves conflicts. Do not let multiple agents mutate the same memory file concurrently. For high-volume logs and retrieval chunks, use compression before model ingestion, but compress at the edge. The canonical memory should remain readable, diffable markdown.
Control Cost By Controlling Recall
Cost control falls out of the same design. The expensive pattern is not one long run; it is repeated full-archive recall. Require each loop iteration to declare which memory entries it loaded and why. Track token use, cache reads, output tokens, runtime, and verification attempts in the run log. Once you have comparable logs across agents and workflows, model choice becomes an engineering decision instead of a preference.
Schedule rot reviews by layer. Identity files change slowly. Rules and hooks change when failure modes appear. Skills need regular pruning because model behavior and tool interfaces shift. Agents are the most fragile because role prompts accrete assumptions. Tools and MCP integrations rot whenever APIs, auth, or CLI flags change. A `rot.md` file with owners, review cadence, and last validated dates prevents memory from becoming an archaeological site.
The end state is not a giant second brain. It is a compact, indexed control plane for autonomous work. The agent starts by reading the router, selects the smallest relevant bundle path, checks state tables, executes through skills and gates, writes evidence, and leaves behind a retrospective patch. That loop is what lets an overnight agent resume, compare, and improve without dragging yesterday’s entire context window into tomorrow’s run.
Key takeaways
- Use the root agent file as a router to indexes, skills, rules, and state, not as a full project memory dump.
- Structure memory as OKF-style markdown bundles with metadata, concept IDs, and nested indexes for progressive disclosure.
- Separate synthesized knowledge, run logs, gotchas, retrospectives, and durable state tables so resumed agents do not infer progress from chat history.
- Make retrospectives patch memory narrowly from evidence: one gotcha, one skill fix, one stale-doc marker, or one state correction at a time.
- Route models and context by phase, and measure token use, runtime, cache reads, and verification attempts across comparable runs.
- Control cost by controlling recall: every loop iteration should load the smallest justified memory slice and record what it used.