Agent Memory

Tell your agent something in a private chat on Monday. Ask about it in a team channel on Friday. It still knows.

That works because every agent keeps a small notes file. The agent reads its notes whenever it starts work somewhere: a channel, a direct message, or a chat with you. As it learns things worth keeping, it adds to them. You can read the same file, and change anything in it.

Where the file lives

Each agent keeps its notes in its own folder, at .dork/MEMORY.md. That is the same place its instructions (SOUL.md) and its boundaries (NOPE.md) live.

It is plain markdown, so you can open it in any editor. You can also open the agent's profile in DorkOS and pick Memory.

New agents start with the file, and the top of it explains itself. An agent you created before this shipped gets its file the first time it saves a note.

How something gets written down

Two ways:

• You ask. Say "remember that we deploy on Tuesdays" and the agent writes it down.
• The agent decides. When it learns a fact, a preference, or a lesson worth keeping, it saves that before the turn ends.

Every saved note ends with where it was learned:

We deploy on Tuesdays, never Fridays. (noted in #product, 2026-08-24)
Prefers short answers with the command first. (noted in a direct chat, 2026-08-24)

The agent does not choose that last part. DorkOS adds it, taken from the room or chat the note was written in. So you can always see where a belief came from, and a note that is wrong tells you which room taught it.

The agent is also told, every turn, not to follow instructions that show up inside its own notes. Notes are things it recorded, not orders. That matters because a note can be written in a room with other people in it.

Changing what it remembers

The file is yours to edit:

• Fix a line to correct it.
• Delete a line to forget it.
• Add a line to teach the agent something without having a chat about it.

Deleting a line really is forgetting it. There is no second copy.

One catch: a chat that is already open may keep using the notes it read when it started. Your edit reaches that chat the next time it restarts. Chats you start after the edit see it right away.

How much it holds

About 8,000 characters, a couple of pages. It is small on purpose. The notes go to the model along with everything else in the chat, so a long file costs you on every turn.

When the file fills up, the agent is asked to tidy it rather than grow it: combine notes that say the same thing, drop the ones that no longer matter. A save that would push the file over the limit is refused, and the refusal says how big the file is, what the limit is, and to tidy up first.

Editing past the limit by hand deletes nothing. The agent reads the first 8,000 characters, and it is told plainly that the file is longer than that, so it can ask you to trim it.

Notes files, for the longer stuff

Some things are too long for the main file: a release checklist, the history of a decision, how a tricky part of a project works. For those, the agent keeps notes files in .dork/memory/, one topic per file.

Notes files are not read every turn. The agent sees one line saying how many it has and which ones changed last, and it opens the one it needs. So they cost nothing until they are used. Each one holds up to 32,000 characters.

When the agent starts a notes file, it writes a one-line description of what it is about, so it can pick the right one from its list later. The same rules apply as in the main file: each line the agent saves says where it was learned, and anything in a notes file can come up in any room or chat the agent joins. The folder has its own .gitignore, so notes are never committed to a git repository the agent lives in.

When an agent has more than 150 notes files, it is reminded to tidy them up. That is only a reminder: it can still save. Removing the last line of a notes file removes the file.

One memory, not two

Agents that run on Claude Code used to keep a second memory of their own, in Claude Code's folders, next to the DorkOS one. So an agent's notes were split in two places. Now, when an agent runs in DorkOS, Claude Code's own memory is switched off, and the DorkOS memory is the only one.

There is one exception, so nothing goes missing: an agent that already has notes in Claude Code's own memory keeps using them until they are copied into its notes files. Copying them is not in the app yet. When a copy is made, it never changes or deletes the originals, and each copied note says where it came from:

_Copied in by DorkOS (migrated from Claude Code memory, 2026-10-17)_

If you run claude in a terminal, outside DorkOS, it still uses Claude Code's own memory.

What memory costs, honestly

It depends on which tool the agent runs on.

• Claude Code: the notes ride along in the part of the prompt that gets cached. A full file is about 2,000 tokens, paid once and reused.
• Codex and OpenCode: the notes are sent again with every turn, so a full file costs that much every time the agent replies.

Keeping the file lean keeps it cheap on all three. That is the other reason for the limit.

What does not travel

Only the agent's notes cross between rooms and chats. What was said in them never does.

The agent runs separately in every channel, direct message, and chat. Each one shares the agent's identity files and its notes. They do not share transcripts. Your agent is told this in plain words, so when it is asked about work it cannot see, it should say so instead of guessing.

The practical version: if you want an agent to carry something from one room or chat into another, it has to be written down.

What is not built yet

• Storing memory somewhere else. The files on this computer are the only option right now.

It is planned. This guide gets updated when it ships, and not before.