Memory
Some things are worth telling an Agent only once: how you like commit messages written, which package manager the project uses, the review conventions your team follows. Memory gives ZCode Agent a project-level long-term memory, so this kind of information carries over into future sessions instead of being repeated at the start of every conversation.
Once enabled, ZCode reviews each successfully finished conversation round in the background and decides whether anything is worth keeping long-term — your preferences, corrections you made to how the Agent works, project goals and constraints, or external references you shared. Whatever it saves is automatically brought back into context in later sessions of the same project.
You can also manage memory directly in conversation: say something like "remember that we deploy from the staging branch" to save it immediately, or "forget what I said about the deploy branch" to remove it.
Memory is off by default and requires ZCode v3.6.4 or later. Turn it on per the next section.
Enabling Memory
Open Settings → General and switch on Memory.
Two things to know about the toggle:
- It applies to new sessions. Changing the setting affects newly created sessions and sessions restored after an app restart; conversations already in progress keep whatever setting they started with.
- It can increase token usage. With Memory on, ZCode may make additional model requests to extract and recall long-term context. You can keep an eye on consumption in Usage Stats.
What Gets Remembered
Memory focuses on four kinds of information:
| Type | What it covers | Example |
|---|---|---|
| User | Your identity, expertise, and preferences | "Prefers pnpm and conventional commits" |
| Feedback | Corrections or confirmations about how the Agent should work | "Don't auto-fix lint errors outside the files being changed" |
| Project | Project goals, constraints, and progress | "The site must stay compatible with Node 20" |
| Reference | External resources you've shared | "Design specs live at the team wiki URL" |
Just as important is what Memory deliberately doesn't record: code structure and git history (the Agent can always re-read those), anything already covered by project instruction files, and one-off details that only matter within the current conversation.
How It Works
After a conversation round completes successfully, a background process reviews the recent exchange. If it finds something worth keeping, it writes the fact as a small Markdown file and updates a MEMORY.md index; if not, nothing is saved. This happens after your turn finishes, so it never slows down the conversation itself.
In later sessions of the same project, the index is loaded into the Agent's context automatically — no action needed on your side. Memory is scoped per project: what ZCode learns in one workspace never leaks into another.
Where Memories Are Stored
Memories are plain Markdown files stored locally on your machine:
~/.zcode/cli/memories/projects/<project>/memory/
├── MEMORY.md # index, one entry per line
└── *.md # one file per saved fact
Nothing is uploaded anywhere as part of the Memory feature. Since they're ordinary files, you can open, edit, or delete them by hand at any time — deleting the project's memory directory resets its memory completely.
Limits and Notes
- Off by default: enable it per project workflow needs in Settings → General.
- No in-app management page yet: to review or clean up memories, ask the Agent ("what do you remember about this project?" / "forget ...") or edit the files on disk directly.
- Remote workspaces are not supported: memory extraction only runs for local projects in the current version.
- The index is loaded with a size cap: very large memory sets get truncated, so concise entries work best — the automatic extraction already keeps entries short.
- Not the same as the MCP memory server: Memory is a built-in ZCode capability and works without any MCP configuration. If you already use a memory-type MCP tool, the two are independent.