The Nervous System Pattern: Persistent Memory for Coding Agents
Coding agents have a memory problem. The session ends, context resets, and everything figured out about the codebase is gone. Here's a pattern that fixes it.
Coding agents have a memory problem you have already felt. The session ends, the context window resets, and the agent loses everything it figured out about your codebase. But that is the easy half. The harder loss is everything you contributed during that session: the steering, the corrections, the load-bearing arguments for why the design or architecture landed where it did.
I have started asking for a dump of my own guidance before context compaction just to have some artifact of my input.
/nervous-system is the skill I built to fix this. It maps onto a codebase the same way a nervous system maps onto a body.
The topology
Your project’s central nervous system (CNS) lives in .cns/ and holds cross-cutting context: architecture, design language, product goals, research background. Its peripheral nervous system (PNS) lives interleaved with code itself: src/engine/index.md, components/Button/index.md, one index.md per meaningful module, linked upward through parent fields in frontmatter.
That is the structure. The interesting parts are how it is maintained.
Design choices
A graph, not a flat collection. Adding parent links makes the collection walkable. Ask “what is our current architecture?” and the agent can summarize at a high level, walking from .cns/architecture down the tree as you ask for more details. Make a decision deep in src/engine/pipelines/ and it has a path to bubble upward if it matters higher up.
Plans dissolve into the graph. Most spec-driven tools accumulate. Every change ships with a proposal, a plan, a tasks file, a design doc. Those files stick around long after the change is merged. The next change touches the same code, the old artifacts go stale, and you end up with a graveyard of plans nobody trusts. Spec-debt is real, and it compounds.
/nervous-system plans are ephemeral. After a task executes, the agent shards the plan: distributes its decisions into the relevant index.md nodes throughout the PNS, next to the code each decision actually affects. From there, bubbling walks the parent chain, lifting significant decisions upward: module-level, then architecture, occasionally all the way to .cns/index.md. Trivial decisions stay local. The plan file is deleted.
The graph is the only persistent artifact. There is no growing pile of obsolete markdown going stale the moment something else touches the same file. The same workflow that ships code is what keeps the documentation current.
Reconciliation. When a PNS document node is marked dirty, the agent runs reconcile: read the node, update the code to honor human intent, re-shard understanding into the appropriate documents, prune stale decisions, mark clean. The graph and the code are two views of the same thing, and reconcile is what makes them agree.
Append-only human notes, rewritable agent body. Every node’s frontmatter has a human_notes field. The agent can append to it but cannot rewrite or delete what is already there. The body below the --- is agent-authored and freely rewritten on reconcile.
This is the choice I am most committed to. human_notes becomes a running log of human direction. The agent records what you told it, in order, and that record never silently changes. Your original steering is always sitting there, with everything added since. No silent revisionism.
Two flat files that bracket the present. .cns/intent.md is a priority queue of forward-looking work, written in plan mode and consumed in execute-task. .cns/log.md is the backward-looking record of what the agent has actually done. Neither is a node. The graph holds state; intent.md holds what is coming; log.md holds what just happened.
Three modes for three shapes of work
You do not engage with a project the same way every day:
Explore is conversational. “What is our current architecture? Why X over Y?” The agent traverses the graph, answers, appends new direction to human_notes.
Plan is collaborative. The agent proposes upcoming work into intent.md. You approve, modify, redirect.
execute-task is hands-off. Plan to implement to test to commit to shard to bubble to validate to log to push. Graph updates are a first-class output of the work, not a follow-up chore.
Where it sits among other approaches
There are other clusters of tools chasing pieces of the same problem:
Spec-driven workflows (Spec Kit, OpenSpec, GSD) organize work around the change: spec, plan, tasks, execute, archive. Feature-scoped, retire after archive, but artifacts still pile up in the repo. They can sit on top of a nervous system, feeding it intent the graph then dissolves.
Distributed AGENTS.md (a Linux Foundation standard, with OpenAI shipping 88 of them) has the right physical layout but stays flat: no parent links, no propagation. /nervous-system is what you get when you turn that pile of files into a graph.
Auto-maintained codebase wikis (Google Code Wiki, DevMem, REAP, Karpathy’s LLM Wiki) share the iterative-sync philosophy. What gets lost in the centralized version is the why. The human direction behind a decision is the part code cannot tell you on its own.
Built-in agent memory (Copilot Memory, VS Code memory tool, CLAUDE.md Learnings pattern) is vendor-managed, sometimes auto-expiring, scope varies. Useful but opaque, and it goes when the vendor goes.
AST-based code-structure indexes (Tree-Sitter graphs, dependency analyzers) describe call graphs and edges. They describe intent; this describes why. Complementary, not overlapping.
The contract
/nervous-system is a SKILL.md, a directory layout, and a few Python scripts. Apache-2.0. Built for Hermes by NousResearch and Teknium, but the contract is portable. Any agent that reads a skill and runs scripts can use it.
Project knowledge should not be something the agent reconstructs every session, and a static instruction file is not quite enough. It is a graph the codebase carries with it.
The repo: github.com/AndrewTBurks/nervous-system