An essay on the memory system

How Codumentor remembers

Memory is several systems, in people and in Codumentor. Each one holds a different kind of thing, for a different length of time, and gets it back in a different way. This page describes the four layers Codumentor has, the one now in beta and off by default, and where the comparison with the human mind stops holding.

We are proud of this design and careful about what we claim for it. Where something is shipped, we say so. Where it is in beta or only planned, we say that too.

The memory map Codumentor's memory layers placed by how long they last (left to right, from seconds to years) and whose memory they are (top to bottom: this conversation, you, your team). Working memory spans seconds to one conversation. Episodic memory runs from one conversation to years. Skills last weeks to years, for you and for your team. Organizational memory serves the team over weeks to years. Personal agentic memory, in beta and off by default, is drawn dashed in your row. Seconds A turn A conversation Weeks Years This conversation what is in view You one person's history Your team shared, curated Working memory · the context window and its compaction Episodic memory · your earlier conversations Skills · yours Personal agentic memory · beta Organizational memory Skills · project and organization Dashed: in beta, off by default. Everything else ships today.

How long each layer holds on to something, and whose memory it is. The dashed band is in beta and off unless your administrator turns it on: what the organizational curator does for a team, done for a single person.

Why more than one

Nobody remembers with a single store

Psychology settled long ago that "memory" names a family of systems. Larry Squire's taxonomy splits it into declarative memory, which you can state (facts, events), and non-declarative memory, which you show by doing (skills, habits). Alongside both runs a small, fast working memory that holds what you are thinking about right now. Each system is good at one thing and bad at the others, and the mind gets its reach from using them together.

An assistant faces the same problem. What it needs to keep in front of it during this task, how it does a kind of job, what happened in an earlier conversation, and what an organization has learned over years are different kinds of knowledge. They have different lifetimes and different owners, and they come back by different routes. A single big store would get all four wrong, so Codumentor keeps them in separate layers.

Working memory

The context window, and the art of letting go

In the mind

George Miller's 1956 paper put the span of immediate memory at "seven, plus or minus two" items. Later work by Nelson Cowan brought the honest figure closer to four chunks. What matters is that working memory is small, and you get by because you keep compressing: you hold the gist, not the transcript.

In Codumentor

The model's context window is its working memory: everything it can see while it decides the next step. It is far larger than four chunks, but it still runs out, so Codumentor compresses it automatically as the conversation grows.

Context budget with the default 262,000-token window: compaction triggers at 245,616 tokens and cuts the prompt to about 122,800. 0 ≈122,800 245,616 262,000 After compaction: half the trigger Trigger Window (16,384 kept in reserve)
Drawn to scale for the default window. A different model profile has a different window, and the same proportions apply.
Where the analogy bendsA bigger window is not a better memory. Models, like people, attend less reliably to the middle of a long context than to its beginning and end. Compaction exists because a focused prompt beats a full one. The summary is a reconstruction, and it can lose a detail, which is why it is shown to you rather than hidden.
Procedural memory

Skills: knowing how

In the mind

You do not recall how to ride a bicycle. The situation calls up the procedure and you ride. Procedural memory is triggered by context: the right cue brings back the whole routine, without you searching for it.

In Codumentor

A skill is a written procedure: a SKILL.md file describing how to do one kind of job well, such as a release checklist, a review routine or a house style. The assistant always has a one-line description of each skill in view, and when your task matches one, it loads the full procedure.

<!-- in view on every turn: names and one-line cues, never the full text -->
<available_skills>
  release-checklist   Cut a release: version bump, notes, tag, verify build
  review-migration    Review a database migration for locking and rollback
  house-style         How this team writes commit messages and changelogs
</available_skills>

That index works like a cue. The skill's name and description sit in the assistant's view on every turn, so a task that looks like a release brings up the release checklist without anyone asking for it. The full procedure is loaded only then, with at most five active at once, so the skills you have do not crowd the working memory above. You can also call one directly by typing /skill-name.

Skills come from four places, and the narrower ones complement the wider:

Who writes them

Today, people do. Codumentor reads skills but does not write them. Every skill it uses was written by someone, and the learning layer described below cannot create one either: an adopted rule can only add a note to what the assistant reads.

We plan to change that. Procedural memory is where experience pays off most: once a job has gone well a few times in the same way, the way it went is worth writing down. Other agent systems already draft skills from their own work, and the approach has proved itself there. Our plan is to do it the way the rest of this page works. Codumentor will notice a procedure that keeps working, draft it as a SKILL.md and offer it to you. It becomes a skill only after you have read it and said yes. This is not built yet. Until it is, this layer grows only when someone writes a skill.

Where the analogy bendsHuman procedural memory is implicit. You cannot read your own habits, and changing one takes months. A skill is plain text: you can open it, see exactly what the assistant will do, correct a line, and the change applies to the next turn. In this respect the machine is easier to change than we are.
Episodic memory

Remembering what happened

In the mind

Endel Tulving named it in 1972: the memory of specific events, each with its own time and place. He later called it "mental time travel", the ability to go back to an earlier moment and look again. It is also associative: a single distinctive word can bring back a whole afternoon.

In Codumentor

Your earlier conversations are your episodes. Say "like last time" or "as we decided", and the assistant searches your history and rereads what it finds. Every result links to the conversation itself, so you can see what it read.

Recall also happens unprompted. At the start of a turn Codumentor looks for words in your message that are distinctive in your own history. A word has to appear in at least one of your conversations and in no more than about twenty-five of them; anything more common is background noise for you, whatever a dictionary says. If two such words lead to the same old conversation, that conversation is offered. A single word is enough only when it is very rare, three conversations or fewer.

Most turns recall nothing, and that is by design. When it does recall something, it offers a short list of conversations, not their content. The assistant still has to open one, and it is told the list was found by keyword and may be off. This layer stores no copy of anything, makes no model call, and reaches only your own conversations. One you have deleted stays deleted.

Recency weight for a recalled conversation: halves every 60 days and never drops below 0.4, reached at about 79 days. 1.0 0.5 0.4 0 today 60 days 120 days 180 days half weight at 60 days floor from ~79 days: old, never erased
How much an older conversation's match counts. Hermann Ebbinghaus measured the human version in 1885: a steep early loss, then a long, nearly flat tail. This curve has the same shape on a calmer clock, and its floor means a strong old match is turned down, never forgotten.

You control it under Settings → Extensions: whether recall happens automatically, how eagerly (Focused, Balanced or Broad), and whether it looks only in the current workspace or in all of yours.

Where the analogy bendsFrederic Bartlett showed in 1932 that people rebuild a memory each time they recall it, and drift a little with every retelling. Today's recall does not retell: it goes back to the original conversation and reads it again. The learning layer below, now in beta, does retell, because getting from what happened to what it meant takes a retelling. The difference from a human memory is that the original is never lost. Every lesson it draws points back to the conversations and to your own words it came from, so a retelling can be checked against its source and written again from it. Nor does any of this forget on its own: rules you can read decide what it may remember.
In beta · agentic memory, for you

From what happened to what it means

People do not keep their episodes forever as episodes. Over nights and years the brain draws the general out of the particular. You forget the forty separate times you fixed that build, and you keep the lesson. McClelland, McNaughton and O'Reilly described this in 1995 as two systems learning together: one records events quickly, and the other slowly extracts what they have in common. What results is semantic memory: knowledge you no longer remember learning.

Codumentor already has this second system. It is the agentic memory curator, and it works for an organization. A personal counterpart, which learns how you like to work, is now in beta.

What already exists, at the organizational scale

After each answer, a curator runs in the background and reads the exchange. It asks one question first: is there anything here worth keeping? Most of the time the honest answer is no, and the run ends. When there is something, such as a naming trap, a decision and its reason, or a workaround nobody wrote down, the curator checks what the knowledge base already says. Then it creates a note, updates one, or retires one that is no longer true. It works in a throwaway copy and publishes the result as a single git commit of plain Markdown, so every change the curator makes can be read, compared and reverted.

When someone later asks a related question, the most relevant notes come back first as short Rapid Direction Cues, placed before the assistant starts. Likes and dislikes change how much a cue counts. Terms that turn up everywhere are demoted, so they are found when someone asks for them but are no longer offered unprompted.

The same idea, one person's scope

The personal version is a sibling of that curator, not a replacement. It is a separate learner with its own store, kept per person, but it has the curator's habits: what it keeps is plain Markdown you can read and edit, and every lesson points back to the conversations it came from. We call the design experience distillation. It learns how the assistant should work with you: how much to verify, how to report, when to ask, how much to do on its own. Facts about your code are not its business. When organizational memory is present, it passes those to that curator as hints.

In beta, off by default. We are still testing it. It works, but it is not settled: what it proposes, how often it asks and what the panel shows are still changing as we see how people use it. Out of the box it does not run at all. Your administrator has to turn it on for your deployment. If they have, it is on for you by default, and you control it under Settings → Extensions with Learn from my conversations. Turning that off stops it noticing anything new, and also pauses the rules you have adopted.

Two ways it learns

The best moment to learn is when something has just gone wrong and you are still paying attention. A lesson that only appears hours later in a panel comes after you have already been let down a second time. So there are two paths, and both feed the same notes and rules.

What you can see and undo

The What I've noticed panel puts first the notes that matter most: the ones you stated, and the ones seen in more than one conversation, ranked by how many conversations and how recently. The rest is folded away under Seen once, or less often. For each note you can answer Yes, that's right, Not really or Make it a rule. A note you dismiss is kept, so it is not proposed again. Under Your rules you can edit, renew or retire each rule, and a rule expires after 90 days unless you renew it. Its "applied" count says how often the rule was put in front of the assistant, not how often it was followed. Next to it you see what happened in those turns: liked, disliked, stopped or corrected. You can export all of it.

  1. Recall your conversations Shipped

    The episodic memory described above: search and reread on request, plus the turn-start offer.

  2. Episodes Beta

    Each quiet conversation becomes an episode record pointing back to the original: what happened in it (Stops, thumbs, failed tools) and a one-line summary. Codumentor also records which of your rules were in view on each turn, so it can later tell whether a rule helped. One you delete is dropped from the episodes as well.

  3. What I've noticed Beta

    Lessons proposed from your reactions and from what recurs across conversations, shown in a "What I've noticed" panel. They change nothing until you act on them.

  4. Rules you approve Beta

    A note you approve becomes a standing rule. It expires unless renewed, can be retired, and every time it is put in front of the assistant is logged.

  5. Beyond a note Research

    Today a rule can only add a note to what the assistant reads. Rules that do more, such as switching mode or asking before acting, and anything that would act without you, remain research.

Nothing changes behavior without a human having said yes.The governing principle of the design

In the beta this principle is held strictly. Every rule starts with your click. The one exception is a setting you turn on yourself: Adopt rules I state without asking, off by default, adds a rule you state at once and shows it with an Undo button. The principle is where we start, not a promise that can never change. When the feature has shown its value, and the record of what people adopt, edit and undo shows that its proposals can be trusted, we may let it act on its own in narrow, measured cases. If that happens, this page will say so, and every rule will still be yours to read and undo.

That principle comes with another: memory is an injection channel. A web page or a tool's output may serve as evidence for a claim, but it can never write a policy. A memory that steers an assistant has to be held to a higher standard than one that only informs it, and the design is built around that difference.

Where the analogy bendsThe brain consolidates without asking you. That is efficient, and it is also how people end up with confident lessons drawn from three unlucky days. Codumentor's consolidation is slower than a brain's on purpose. A lesson has to turn up in two separate conversations before it is even shown to you as a note, and you read and approve every rule it draws.
Organizational memory

What a team knows that no one person does

In 1985 Daniel Wegner described transactive memory: couples and teams spread remembering across their members, and the group knows who knows what. Organizations lose it all the time, when the person who knew why the billing module has two names leaves, or when a decision outlives everyone who took it. Most of what makes legacy work dangerous is this kind of knowledge. It is not in the code, and it was never written down.

Codumentor's organizational memory is that knowledge, captured as the work happens and given back when the work needs it. Notes record their author's role, and a note from someone with more authority counts for more. Each note lives in a Git repository that your team owns and can read like any other documentation. A person can vote on a note or flag it for review, and the curator can retire a note that has stopped being true.

Your administrator decides whether organizational memory is turned on for your deployment. If it is, you will see memory cards in your conversations. Organizational memory describes how to read them and how your votes improve the knowledge base for everyone.

A good colleague keeps the task in mind, knows how the work is done, remembers what you did together last month, and knows what the team learned before either of you arrived. Codumentor has a layer for each of those, and each layer is built so you can see what it holds.

We borrowed the names from psychology because they describe the shape well. We have tried to be exact about where that shape ends, because a memory you can read, correct and refuse is worth more than one that only resembles ours.

Sources

  1. Miller, G. A. (1956). The magical number seven, plus or minus two. Psychological Review, 63(2).
  2. Cowan, N. (2001). The magical number 4 in short-term memory. Behavioral and Brain Sciences, 24(1).
  3. Squire, L. R. (2004). Memory systems of the brain: a brief history and current perspective. Neurobiology of Learning and Memory, 82(3).
  4. Tulving, E. (1972). Episodic and semantic memory. In Organization of Memory. Academic Press.
  5. Ebbinghaus, H. (1885). Über das Gedächtnis. Duncker & Humblot.
  6. Bartlett, F. C. (1932). Remembering. Cambridge University Press.
  7. McClelland, J. L., McNaughton, B. L., & O'Reilly, R. C. (1995). Why there are complementary learning systems in the hippocampus and neocortex. Psychological Review, 102(3).
  8. Wegner, D. M. (1985). Transactive memory: a contemporary analysis of the group mind. In Theories of Group Behavior. Springer.
  9. Liu, N. F., et al. (2023). Lost in the middle: how language models use long contexts. arXiv:2307.03172.