Memory

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

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, and device entries live under memory/<dimension>/ in the MagicFrog data directory.
• task entries live inside the project, at .magicfrog/memory/.
• revision increments on every write. Writes can carry an expected revision; a write against a stale revision fails instead of silently overwriting.
• device entries additionally record a machine frontmatter key binding them to the computer that wrote them; imports preserve that binding.

Legacy machine/ and project/ layouts keep working, read as device and task memory respectively; new notes go straight into the five dimensions.

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), and
• skills (the skills/ prefix).

Layers are defined in a layers.json file next to the memory tree: adding a layer for a team or workflow is one config edit.

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

At the start of each session the agent reads the memory of every dimension in scope, most specific first (task, agent, user, account, then device). Updates replace the whole view, so the agent never mixes old and new.

So each agent sees the memory of its own task and its own agent dimension — never anyone else's.

Cloud roaming

The four chain dimensions (account, user, agent, task) sync across the machines on your account, 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.