# Project Memory

> A persistent knowledge base attached to a project, written and read by the agents themselves while they work: architecture, decisions, conventions, pitfalls, the state of each feature.

- Area: Desktop app
- Plans: All plans
- Last checked against the product: 2026-09-28
- Web page: https://agentsroom.dev/docs/project-memory

## What it does

A persistent knowledge base attached to a project, written and read by the agents themselves while they work: architecture, decisions, conventions, pitfalls, the state of each feature. It answers "agents forget everything between sessions": what one agent learns today is read by every agent, on every machine, by every teammate who opens the same repository. Notes are markdown, live in two roots (`features/`, one note per feature, and `global/` for repo-wide knowledge), link to each other with `wiki-links`, and are mirrored as read-only files inside the project so agents can grep them before calling any tool.

## Where to find it

- Inside a project: the **Project memory** item of the dock (group **Knowledge**, brain icon; the badge is the note count). The modal reuses the Skills Library layout with **List view** / **Graph view**, search, folders, **Import from Obsidian** and **Import from project**.
- Its scope tabs: the project, **Memory of <folder>** (when the project is in a zone), **Global** and **Agents** (**Agent notebooks**, "What each of your agents has learned").
- On an open agent: the brain button **Memorize now** in the session header, and the **Memorize this session?** dialog when you close a session.
- In the agent editor: the **Always memorize** toggle, and **Memory notebook** with that agent's note count and an **Open** button.
- Project settings > Agents: the **Project memory** master switch.
- Command palette (Cmd K / Ctrl K): the "Memory" group searches note names, descriptions and bodies.

## How to use it

1. Work normally. Agents are told to read the memory before exploring the code and to save a note after any significant outcome (update-over-create: a note with the same name is enriched, not duplicated).
2. Click **Memorize now** to have the current session write what it learned without closing it: the instruction is prepared in the composer, you can amend it, then send.
3. Close a session: the dialog offers **Memorize** or **Close without memorizing**, with three opt-outs (this agent, this project, never). Sessions under ten minutes and quick agents are not asked.
4. Browse or edit notes yourself in the modal: **New memory**, folders, tags, a "Contains..." description that future agents search on. **Graph view** draws the wiki-links; recent notes are brighter, notes untouched for 60 days fade.
5. **Import from Obsidian** maps a vault (or one folder of it) onto the memory: folders, frontmatter description and tags, `links` rewritten. Nothing is preselected, because the memory is shared.
6. Reuse a note elsewhere: hover a note of the project scope in **List view** and click **Copy to another project** ("Writes this note into another project of your account"). Pick the target in the list, and the copy lands at the root of that project's memory, with a numbered suffix if the name is already taken there. The original is untouched. The same action sits on each row of the **Other projects** band that an **Auto** search returns, which is how you pull a note from another project into the one you have open.

Scopes: the project is the default. The same modal shows the account memory (tab **Global**), the folder's zone memory when the project sits in a folder (**Memory of <folder>**) and every agent's own notebook (**Agents**). What an agent writes for itself is readable and correctable there, or from **Edit agent > Memory notebook > Open**, which shows that one notebook alone. See [Scope Levels](https://agentsroom.dev/docs/scope-levels.md).

**History** (note editor, existing note): every save that changes a note (name, description, body, tags), by you or by an agent through `memory_save`, keeps the previous version. The list shows each version's author and date, the selected one is compared line by line with the current body, and **Restore this version** loads it in the editor: save to keep it, the current state stays in the history. The history is shared like the note: every member of the project sees it. The account memory has its own history.

## Settings

- `memoryEnabled` (project, Project settings > Agents > Project memory): master switch, default on. Off = agents are forbidden the memory tools, no close dialog, no Always memorize block.
- `skipMemorizeOnClose` (global, and project override): never show the memorize-on-close dialog. Also set by the "Don't ask again" options of the dialog.
- `backlogMemorizeCloseOnDone` (global, Settings > Backlog > Memorize and close on done; project override): when a ticket reaches Done, its console is asked to memorize, then closed. Off by default.
- Per agent: **Always memorize** (agent editor and scheduled tasks), the agent persists learnings at the end of every turn.

## Agent tools (MCP)

- `memory_list`: folders and notes with their retrieval cue, full folder path and a preview. Accepts `scope`: `project` (default), `folder`, `global`, `agent`. A `project` argument reads a sibling project of the same account instead of this one.
- `memory_get`: full body of one note, by id or exact name (wiki-links use names). Always JSON. Also accepts `project` for a read in a sibling project.
- `memory_save`: create or update a note by name; `mode: "append"` adds a section without reading the note first (never creates). `mode: "edit"` with `find` (the exact passage, copied verbatim) and `content` (its replacement) corrects one passage in place, so the fix sits next to the claim it fixes and the note never travels through the agent's context; the call is refused and the note left untouched when `find` matches nothing or more than once, and an empty `content` removes the passage. Append and edit never create a note, and `description` is optional for both. The answer of an edit carries an excerpt around the change instead of the whole body. The folder actually used is returned. Writes always land in the project the agent runs in.
- `memory_delete`: erase one note, for cleaning up the agent's own mistakes or on explicit instruction. Never removes an emptied folder.

## Providers

All providers, no difference: the tools are served by the AgentsRoom MCP server, and the markdown mirror is readable by any CLI. The read-first instruction is injected in every agent's boot prompt whatever the CLI.

## Mobile

No memory screen on the phone. An agent launched from the mobile companion runs on the desktop and gets the same four tools, so it reads and writes the same memory.

## Limits

- Requires being signed in: the memory is stored server-side so it can be shared. Offline, the local cache is served; an edit made in the modal while offline can be lost if the server copy changed meanwhile (last write wins, no merge). Notes written by agents take a safer route: one note at a time, retried on conflict, so two agents saving at the same moment no longer overwrite each other.
- Shared by capability: anyone signed in who opens the project (its id is committed in the repo) reads the same memory. Do not store secrets in it; agents are told not to.
- The mirror reflects the last sync, not the live server: a teammate's note appears at the next open, edit or agent write. `memory_list` forces a fresh fetch.
- No note quota, no plan gate.
- Obsidian import: 2,000 notes maximum per scan, markdown files only.

## Common questions

- **How is this different from CLAUDE.md or AGENTS.md?** Those are static instructions you write by hand. The memory is dynamic and agent-written; the two complement each other.
- **Do teammates see the same memory?** Yes, keyed on the project, not on your account. Cloning and opening the repo is enough.
- **Why did an agent say the project has no memory?** An absent mirror folder (for example in a worktree) does not mean an empty memory; agents are told to fall back on `memory_list`. If it persists, check the **Project memory** switch in Project settings.
- **I chose Memorize and the question came back when I closed the agent again.** Fixed on 2026-09-23: the dialog is asked once per conversation, even if you switched project or opened the Open space in between. A new conversation of the same agent gets its own question.
- **Can I turn off the close dialog only?** Yes: **Never ask again** in the dialog, or `skipMemorizeOnClose`; agents keep writing during the session.
- **Deleting a `.md` in `.agentsroom/memory/` deletes the note?** No, the mirror is regenerated from the server. Delete from the modal or with `memory_delete`.
- **Can I reuse a note in another project?** Yes: **Copy to another project** on the note card. Going through the Global library first is no longer necessary.
- **Can an agent fix one wrong sentence in a long note without rewriting it?** Yes: `memory_save` with `mode: "edit"`, `find` set to the exact passage and `content` to its replacement. The passage must occur exactly once in the note, otherwise the call is refused and nothing changes; the agent is told to quote a longer anchor. This works in every scope (project, folder, global, agent notebook).
- **Can an agent copy a note into another project?** No. `memory_list` and `memory_get` accept a `project` argument to READ a sibling project of the same account, but `memory_save` and `memory_delete` never cross projects: copying is a gesture you make in the modal.
- **An agent rewrote a note and lost something. Can I get it back?** Yes: open the note, click **History**, pick the version before the change, **Restore this version**, then save. The last 50 versions of each note are kept.

## Related

- [Scope Levels](https://agentsroom.dev/docs/scope-levels.md): project, folder, account and agent scopes of the same memory.
- [Skills Library](https://agentsroom.dev/docs/skills-library.md): the sibling library, same UI, for procedures instead of knowledge.
- [Commit Context](https://agentsroom.dev/docs/commit-context.md): keeps the conversation behind a commit, where memory keeps distilled knowledge.
- [Command Palette](https://agentsroom.dev/docs/command-palette.md): searches memory notes.