You told your agent last week which client prefers email over calls, and today it asked again. Or it did remember something, and you have no idea where that memory is, what else is in there, or how to fix the one line it got wrong. Memory you cannot see is memory you cannot trust.
In Bloks, what each agent remembers is plain Markdown in its own folder on your disk. You can open it, read it, change it, and take any change back. This guide shows where it lives, how agents use it, and how to look after it.
How memory is laid out
Each agent keeps two kinds of notes:
MEMORY.md, loaded into every turn. Think of it as the agent’s standing briefing.- Topic files in a
memory/folder beside it, which the agent reads when a topic comes up.
Memory is capped so it stays a briefing, not a transcript: a budget of 200 lines and 24,000 bytes. Anything bigger belongs in a topic file.
Beside each agent’s own notes there are two shared kinds:
- Shared memory, one
MEMORY.mdyou keep for every agent. Agents read it and never write it. - About you, short notes your agents suggest as they learn (how you like answers, your timezone, the names you use). Nothing is added until you keep it, and kept notes reach every agent from then on, so a new hire already knows you.
Where it lives on disk
Everything is in the workspace’s own folder. For Personal, that is ~/.bloks:
| Path | What it holds |
|---|---|
workspaces/ |
Each agent’s own home folder, with its MEMORY.md and topic files |
shared/MEMORY.md |
The shared memory every agent reads |
memory-journal/ |
Every change to an agent’s memory, with the text before and after |
Every other workspace has a folder of its own in the app’s folder: on a Mac, ~/Library/Application Support/Bloks/workspaces/. On bloks-server, BLOKS_DATA_DIR says where the data folder is.
Because these are ordinary files, any editor, search tool or backup program you already use can read them.
How agents use their memory
You do not have to tell an agent to remember. Here is what happens on each turn.
- The briefing goes in.
MEMORY.mdand the shared memory are part of every turn. - Relevant history comes up. Before your turn, an agent looks through its other conversations and its topic files for what is relevant to your words, and says exactly what it was given. Under your message it shows as “Recalled 2 notes”, opening to each excerpt with where and when it was said.
- The agent writes what it learns. CLI engines use
bloks memory(with--topics, or--topic <name>and--writeor--forget), and API engines usememory_write, on their own notes only. - It can look further back.
bloks recallsearches the agent’s own past conversations for a decision, a name or a number. Each result says whose words it holds, so a report from another agent is never taken for your decision.
A few habits are built in. Agents are told never to store instructions that arrive from webhooks or forwarded content. For a temporary fact they write a line ending (until YYYY-MM-DD), which is removed the day after that date. An agent’s memory follows it between rooms and one to ones, so you can ask it privately what it thought of the group’s plan.
Recall before your turn is on unless you turn it off, for one agent in its settings under Memory, or for the whole workspace in Settings, General.
Read and edit it in Bloks
Open Memory on the main rail. A sidebar lists Shared, About you and every agent.
- Pick an agent to see its
MEMORY.mdand topic files, with a meter showing lines and bytes against the budget. - Edit anything in place, add a topic, or forget one.
- Search across every agent’s memory and the shared memory at once.
- Copy picked topics, or picked lines of
MEMORY.md, from one agent to another. - Open Recent changes to see a journal of every change, whether the agent made it during a turn or you made it here, each with its diff and an Undo button.
Undo follows the same rule as undo for files: it only puts a file back if it is still exactly what that change left. An edit you made afterwards is never lost.
The nightly tidy
Once a night, between 01:00 and 05:00, each agent’s memory is tidied: notes are merged, reworded only if shorter, or archived with a reason to memory/archive.md. Lines nobody named stay exactly as they were. The Memory place shows the night’s diary under the meter, with Review and Undo, and the whole night undoes in one press. You can ask an agent to change the tidy setting for you; it proposes the change on a card, and nothing changes until you tap Change.
Rewind leaves memory alone
Rewinding a conversation takes the messages and the files back, but not the agent’s memory notes. If a rewind should also take back something the agent wrote down, undo that entry in Recent changes.
Back it up
Memory is part of the workspace folder, so backing up the workspace backs up every agent’s memory.
- Daily backups. Your workspace is backed up every day, beside the folder rather than in it:
~/.bloks-backupsfor Personal. The newest seven daily backups are kept. - On demand. Settings, Backups writes a whole workspace out to one file, keys left behind, for an empty workspace on another computer to take in.
- On a server.
bloks-server backup --encryptmakes a sealed backup, as described in Install the Bloks server on a VPS with Docker. - Moving computers. Move the folder to a new Mac and its agents come with you, memory and all.
Keep memories apart with workspaces
A workspace is a whole Bloks of its own: its own agents, memory, keys, rooms and settings, in its own folder. Nothing moves between them, so the agents that run your company never read your family’s notes. Make a Business workspace, or one with a name of its own, from the switcher at the top of the window.
In a workspace with other people in it, memory respects who said what:
- What an agent remembers in a member’s private conversation is kept for that person alone, apart from its memory everywhere else.
- Your shared memory is never in a member’s turn, since you wrote it for your own.
- Each person’s notes about themselves are their own.
Bring memory from another tool
If you kept notes in another agent tool, Bring your setup can carry them over. OpenClaw’s MEMORY.md and memory/*.md files come across, and OpenBot memories land in the agent’s MEMORY.md or a topic file. Move your agents from OpenClaw, Hermes or OpenBot walks through it, and the docs have the reference.
Questions
Where does an agent's memory live on disk?
In the agent's own folder inside the workspace's workspaces folder. For Personal that is under ~/.bloks/workspaces/, with MEMORY.md at the top and topic files in memory/.
Can I edit an agent's memory by hand?
Yes. Open Memory on the main rail to edit any agent's files, add a topic or forget one. Every change is journaled with its diff and can be undone.
Does rewinding a conversation change what the agent remembers?
No. A rewind leaves the agent's memory notes as they are. The Memory place has its own undo for those.
Do agents in one workspace see another workspace's memory?
No. Each workspace has its own agents, memory and keys, and nothing moves between them.
Is the nightly memory tidy reversible?
Yes. Each night's tidy is journaled, and the whole night undoes in one press from the Memory place.