Workspace Memory
Workspace Memory gives each workspace a persistent .memory directory for long-lived notes. Use it for stable facts, recurring preferences, project conventions, decision logs, and reference material that should still matter in later tasks.
Memory is enabled by default for new workspaces. Workspace owners can disable it when a workspace should not keep persistent notes.
Enable Memory
- Open the workspace.
- Go to Workspace Settings.
- In the Memory tab, turn on Enable Memory if it is currently off.
- Save your changes.
Once enabled, Meowbert creates a .memory folder at the workspace root. That folder is shared across projects in the same workspace and stays available for future tasks and shell sessions.
What belongs in .memory
Good fits for Memory include:
- Project-specific facts the agent keeps needing.
- Stable preferences such as coding conventions or output formats.
- Reusable references, glossaries, and decision notes.
- Short summaries of previous discoveries that will matter again later.
Avoid treating .memory like throwaway scratch space. Temporary task artifacts usually belong in normal task output files instead.
Keeping Memory organized
Meowbert keeps Memory as a set of topic files rather than one long note. Each file opens with a one-line description and is organized under headings, and MEMORY.md links to them. Topic files can be as detailed as they need to be, since search finds what's in them; what agents leave out is anything a later task wouldn't use, such as progress logs. If you edit Memory by hand, following the same shape helps the agent find things.
File index
When an agent reads a file a later task will likely need, usually something in Project Context, it can save a detailed summary of it to Memory. An entry can cover one file, a folder, or a few related files. Later tasks check for an entry before rereading, and work from it when it still matches.
Each entry records how its files looked when they were read, so an agent can tell when one has changed and update the entry. Entries live under index/ in the workspace or Project memory folder, mirroring the paths they describe:
context/specs/api.yaml → .memory/projects/<project-id>/index/context/specs/api.yaml.md
context/specs/ → .memory/projects/<project-id>/index/context/specs/__folder__.mdEntries are ordinary Memory files: Memory search finds them, and you can edit or delete them like any other note.
When several sources explain a topic together, an agent can save a named group entry describing how they relate, with references to the relevant paths or sections. This uses the same freshness checks as individual file entries. Exact terms and quotations remain in the original sources.
Sources and verification
Important Memory claims should retain their source and when they were last checked. Agents distinguish your instructions from verified observations and unresolved hypotheses, rather than treating an earlier agent's report of success as proof.
Refreshes receive the source task and message IDs for each conversation entry. When evidence needs checking, agents can use read_task_evidence to read original messages and recorded tool results in the current Project, including archived results. Long results are read in bounded pages. Incognito tasks and their descendants, along with Memory refresh tasks and their descendants, are excluded.
MEMORY.md — your always-on context
Inside .memory there's a special file: MEMORY.md. Unlike other notes, this file is automatically injected into every run as background context, so the agent always has it available without needing to search for it.
Think of MEMORY.md as the front page of your memory — a compact, high-value summary that's always present. Good things to keep here:
- A short overview of the project or workspace.
- Key commands, workflows, and tooling preferences.
- Coding conventions and output format preferences.
- Active decisions and open questions.
- Links or pointers to more detailed notes elsewhere in
.memory.
Avoid letting MEMORY.md grow too long. Put detailed notes in other files under .memory and reference or summarize them from MEMORY.md instead. The file is trimmed if it gets too large, so keep it focused on what matters most.
When Memory is enabled for a workspace:
- The task composer, quick agent, and follow-up input can show a Memory toggle in the tools menu.
- New task drafts in that workspace start with Memory enabled by default.
- You can still turn it off for any individual task.
With the toggle on, the agent can search workspace .memory during the run. Search matches both meaning and exact words, so a query finds related notes as well as specific names such as a command, file, or error code. Search results include relevant snippets plus the source file path and line range, so the agent can open or update the right note instead of guessing.
Meowbert syncs the Memory index in the background. Searches use the last ready index immediately instead of blocking on rebuilds. If the workspace is still being indexed for the first time, Memory search can briefly return no results while indexing finishes.
See Tool Options for the per-task toggle behavior.
Refreshing Memory
The workspace sidebar includes a Memory page. It previews the workspace MEMORY.md and the active Project MEMORY.md, and its Open in Files action opens the .memory directory in the Files browser.
Workspace owners can enable Automatic Memory Refresh in Workspace Settings → Memory. Meowbert evaluates new activity using the amount of conversation, completed work, and time since the last refresh, then queues bounded refresh tasks only when the accumulated context is likely to be useful. Automatic refreshes are spaced at least three hours apart for each Project.
Each Project can opt out from Project Settings → Memory. Projects are enabled by default, but their automatic refresh setting only takes effect while the workspace-wide automatic-refresh setting remains enabled.
You can also select a Project and choose Refresh memory from the Memory page. A refresh creates a regular task with its own sandbox. It receives the new conversation evidence in inputs/memory-delta.md, can update the workspace and Project Memory files, and is limited to 40 agent steps. If Memory has become disorganized, the refresh also reorganizes it: merging overlapping notes, splitting long files, and fixing links. It uses the normal task execution and platform usage accounting path.
Refreshes in the same workspace run one at a time, since they can update shared workspace notes. Other Projects' refreshes remain queued and continue after the active refresh finishes. Different workspaces can refresh independently.
Set the Agent Preset for refresh tasks in Admin → Models → Specialized runtime with memorySynthesisAgent. Its full preset payload, including model and reasoning configuration, is applied and resolved through the normal model-routing path. If it is unset or unavailable, Meowbert uses the default available Agent Preset.
Working with Memory from Files and Tasks
The .memory folder is part of the normal workspace filesystem:
- Open it from the workspace Files Browser.
- Ask a task to update a memory file in that workspace.
- Reference it directly in prompts with paths like
.memory/preferences.md.
When Memory is enabled, task runs and agent shell sessions also receive these environment variables:
MEMORY_DIRMEOWBERT_MEMORY_DIR
Both point to the workspace .memory directory.
Coordinating concurrent edits
Memory stays directly editable from the shell and Files browser. Agents coordinate shell changes with run_shell using memory_write: true: the command holds a workspace Memory lock while it rereads the latest affected files, merges changes, and writes them. Deletions and reorganizations use the same flag. The lock covers only the foreground command; background writers and persistent shell sessions must not be used for these edits.
index_save takes the same lock automatically. Appended updates merge with the latest entry, and replacing an entry checks the revision returned by index_lookup so a stale replacement cannot silently discard a newer coordinated edit. Independent contributions should use separate topic files where practical.
This coordination is cooperative. Shell commands without the flag and manual Files edits remain available and can race with other writers.
Self-hosted embedding configuration
Server admins choose the embedding model used for Memory search, and can switch Memory search off, in Admin Panel → Platform → Embeddings. See Models & Providers.