Cross-Session Memory for Coding Agents: Rules, Notebooks, and Deletion

A large context window solves “how much information can be stuffed into one task,” not “what remains after the window closes.” Many developers have hit the same frustration: they explain the project’s hard rules clearly—the auth module must not be refactored, the local cache service must be running before tests, static checks must run before commit—and the agent follows them well at the time. Then a new session starts, and it puts the explicitly forbidden refactor back on the table.

This is not simply a missing “memory feature.” More accurately: what you said is not necessarily what the system decides to persist. Whether to remember, at what granularity, and when to expire depend on who holds the decision rights in the product. Breaking this apart is necessary to design a workflow that is both manageable and controllable.

Why Bigger Windows Still Forget Across Sessions

The least confusing analogy is to treat conversation context as memory and cross-session memory as disk. No matter how large memory is, it is cleared when the process exits; disk is what persists across processes. When a coding tool’s session window closes, the workspace switches, or session compression triggers, the original conversation is often no longer fully available. Without an independent persistence layer, hard rules degrade from “current task constraints” into “something once said in passing.”

This produces three common illusions. First, believing that pasting instructions into a very long prompt solves everything; in reality, the prompt only covers the current window. Second, believing that the model automatically upgrades every verbal agreement into a long-term preference; in reality, most implementations filter out one-off instructions. Third, believing that retrieving a similar snippet means the rule is being followed; in reality, the retrieved hit may be a stale conclusion or a bad summary.

The hard part of a memory system is not “how to write things in.” It is two other things: do not mistake an exception for a habit, and decide how stale information is deleted or downweighted. Remembering wrong is more dangerous than not remembering: incorrect memory gets cited repeatedly in later tasks and becomes a systematic bias.

Four Memory Layers That Should Not Be Mixed Together

Industry discussions of “memory” often compare different layers as if they were the same thing, which guarantees distorted conclusions. At least four layers should be distinguished.

The first is a human-written rules file. It lives in the repository or a workspace-agreed path and is reviewed by the team and kept under version control. Its content is usually architecture boundaries, prohibited actions, build and test order, and code style. The advantages are auditability, rollback, and immediate effect in new sessions; the disadvantage is that it does not grow automatically from conversations and requires human maintenance.

The second is compression and summarization within a single long conversation. When context approaches its limit, the system folds early turns and keeps only a summary or key decisions. This solves “do not overflow in the same window,” not cross-window retention. If the compression algorithm treats an exception as a general rule, later reasoning will drift.

The third is the agent’s built-in notebook. During a session, the model or a background task writes entries deemed “worth keeping long term” into local notes. The write timing may be the model’s own judgment, an explicit user request, or asynchronous distillation after the window has been idle for some time. This layer most easily creates the illusion that “if I said it, it will be remembered.”

The fourth is an external independent memory store. Snippets, entities, and preferences are stored in a searchable store, queried by task, and then injected into the prompt. It suits cross-project and cross-person knowledge accumulation, but it also introduces permissions, contamination, expiration, and evaluation costs. For most small and midsize teams, this layer is often not an immediate requirement.

The four layers solve different problems: the rules file governs “must follow”; compression governs “do not break the current conversation”; the notebook governs “incremental personal or project preferences”; the external store governs “large-scale retrieval and sharing.” Comparing one layer against another produces false capability gaps.

The Core Split: Who Decides What Goes Into the Notebook

The same phrase “remember this” leads to very different product paths, and the underlying question is singular: who holds write authority.

One path is automatic distillation. After the conversation ends or has been idle long enough, a background process compresses the conversation into notes. The benefit is near-zero user operation; the risk is that the model turns a one-time experiment into a long-term constraint, or misses the real hard rules. The idle threshold, summarization prompt, and whether old entries may be overwritten all significantly change the experience.

Another path is model-invoked create-read-update-delete tools. Note-taking becomes an explicit tool, and the model decides during reasoning whether to insert, update, or delete. The benefit is explainability and auditability in the trajectory; the risk is that the model over-records noise or does not know how to merge conflicting entries. Constraints are needed: record only verifiable facts, include timestamps, and ask the human when entries conflict.

Another path is writing back into the code repository. Memory enters version control as documents or comments and is visible to colleagues through merge requests. The benefit is that memory shares the same lifecycle as code; the risk is polluting a shared repository with personal preferences or turning unreviewed conclusions into standards. This suits project-level conventions, not temporary findings from a debugging session.

Another path is subtraction: no automatic memory, and manual rules are mandatory. It feels annoying in the short term but is the most stable in the long term—anything that enters the repository has passed human eyes. For teams with high compliance requirements and many collaborators, this is often the default best option.

There is also a path that lets the model edit configuration files directly. It is flexible, but it amounts to giving “change team standards” authority to a single conversation. Permission boundaries are essential: the model may only change a personal override layer, or changes must go through review.

There is no absolutely correct path, only a path that matches the collaboration model. Personal experimental projects can lean automatic; production repositories should lean toward human-written rules plus a limited notebook.

Store, Retrieve, Delete: A Loop More Complete Than “Write It In”

Store. Distinguish facts, preferences, and task state. A fact is “this service depends on a local cache instance to run integration tests.” A preference is “run static checks before commit.” A task state is “this week we are migrating a module; do not touch auth for now.” Facts belong in the rules file; preferences can go into the notebook but need scope; task state must carry an expiration condition and should be deleted or archived when the task ends.

Before writing, ask three questions: Is this a constraint that still holds across sessions? Will it turn a one-time exception into the norm? Would a colleague misread it as a mandatory standard? Only persist after all three pass.

Retrieve. Reading should not mean stuffing every note into the prompt. Filter by current repository, current task type, and current risk level. For auth and payment work, prioritize security and compatibility rules; for pure copy edits, there is no need to load the full architecture notes. The goal of retrieval is constraint alignment, not “the more information the better.” Overlong memory crowds out the real code and error context.

Delete. A memory system without a deletion strategy becomes a landfill of stale conclusions within weeks. At a minimum, it should support automatic downweighting by item expiration time, one-click clearing of project notes by the user, and invalidation of related automatic summaries when the rules file changes. Deletion should be more auditable than insertion, to avoid “I do not know why it suddenly forgot.”

A Practical Setup You Can Copy

Most teams do not need to start with vector retrieval and an independent memory store. A more stable combination is usually a project rules file under two hundred lines plus a handoff note at task close.

The rules file should contain only hard constraints and operation order, for example: which modules are forbidden to refactor and why; the startup order of local services required by tests; the check commands to run before commit; red lines for logging and secret handling. Use short, executable, verifiable entries, not prose. Keep the file under version control and route changes through normal review.

The handoff note is for “the next window’s self or colleague”: what step the work is at, which risks remain unmerged, and what explicitly not to do. Write it at task close, not while chatting. Treat the note as short-term by default, and archive it after completion or release.

If the product provides an automatic notebook, treat it as a draft area: periodically promote stable conclusions into the rules file and delete bad summaries. Do not let the automatic layer become the sole source of truth.

When building your own agent, design the memory interface as explicit tools and default to refusing writes that lack scope and time limits. State in the prompt: verbal instructions are valid only for the current session by default unless the user confirms “write to project rules” or “write to personal preferences.” This reduces two accidents at the root: “agreed well, forgotten next week” and “misremembered confidently.”

A Checklist for Rollout

Before launching or adjusting a memory strategy, use these checks. Open a new blank session, load only the rules file, and see whether the agent still follows the hard rules. Deliberately say a temporary instruction and see whether the next session inherits it incorrectly. When the rules file and the notebook conflict, which one wins, and is that documented in the system description? After personnel changes, can stale notes be found and cleaned up? Are secrets and internal addresses prohibited from entering syncable memory layers?

The goal of memory is not to make the model “more like a person who remembers things.” It is to make team standards take effect across sessions in an auditable way. Human-written rules guarantee the floor, limited automatic distillation improves efficiency, and deletion and downweighting control contamination. Get these three right, and a new session will not treat last week’s rules as something that never happened.