MagicFrog gives every conversation a long-term memory: a tree of Markdown notes that agents read on each session and can update as work progresses. Memory is organized into five dimensions, and the same note path can exist in several of them — the more specific dimension wins.
The five dimensions
| Dimension | Scope | Roams with your account |
|---|---|---|
account |
Shared across the whole account | Yes |
user |
One user's preferences and context | Yes |
agent |
One named agent, isolated per agent ID | Yes |
task |
One task (project), isolated per task ID | Yes |
device |
One computer only | No — never leaves this machine |
The first four form an override chain, from least to most specific: account < user < agent < task. When the same path exists in several chain dimensions, the merged (effective) view keeps only the most specific one. device sits outside the chain: its entries stay independent rows bound to this computer and never merge across machines.
Agent and task entries can be namespaced with an ID prefix — agent/<agentId>/notes/style.md applies only to that agent, and task/<taskId>/notes/progress.md only to that task. A path without an ID prefix applies to every agent and task.
Where memory lives
Memory is plain Markdown on disk; a text editor is a sufficient memory client. Each entry is one .md file with minimal frontmatter:
---
revision: 3
updated: 2026-10-20T09:12:00.000Z
---
Prefer functional array methods over for loops.account,user,agent, anddeviceentries live undermemory/<dimension>/in the MagicFrog data directory.taskentries live inside the project, at.magicfrog/memory/.revisionincrements on every write. Writes can carry an expected revision; a write against a stale revision fails instead of silently overwriting.deviceentries additionally record amachinefrontmatter key binding them to the computer that wrote them; imports preserve that binding.
Older three-tier trees keep working with zero migration: legacy machine/ entries read as device memory and legacy project/ directories read as task memory, in place. New writes always land on a canonical dimension.
Layers are configuration
Each dimension has layers — path conventions inside the dimension root. Two layers exist by default in every dimension:
core(the dimension root itself), andskills(theskills/prefix).
Layers are defined in a layers.json file next to the memory tree, not in engine code: adding a layer for a team or workflow is a config edit, and new dimensions of work never require engine changes.
Markdown documents under a skills layer are discoverable as a skill source, alongside your repo and home-directory skills — memory notes that say "how to work" become loadable skills.
How memory reaches the agent
Before each session's context is assembled, the effective view of every dimension in scope is rendered into a single <memory> block, ordered most-specific first (task, agent, user, account, then device). When memory changes, the next update replaces the block and says so, so the agent never mixes old and new views.
A session contributes its task binding (the carrier session's task ID) and the agent IDs of everyone on its roster, so each participant sees the task dimension for that task and its own agent dimension — and not anyone else's.
Cloud roaming
The four chain dimensions (account, user, agent, task) are part of the cloud profile sync surface: their portable tree is what uploads and downloads across machines, and every entry's revision makes writes conflict-safe. Device entries never upload — local machine memory stays local.
To move memory by hand, the tree exports to a portable set of Markdown files and imports back; files carrying a machine/ or project/ prefix land in the device or task dimension respectively.