Memory and instructions

Mework gives the model three kinds of standing context: project instructions you write in MEWORK.md files, long-term memory the model keeps for itself in Markdown files, and handoff notes that carry unfinished work into a new conversation.

Project instructions

Project instructions are Markdown files you write for the model: how to build and test, conventions to follow, things to avoid. At the start of every run (each message you send, and each time a conversation resumes on its own) Mework collects them and sends them ahead of the conversation history. They do not appear on the timeline.

Instructions guide the model but cannot grant permissions; for rules that must hold, use hooks or a security level. Editing an instruction file mid-conversation changes the start of every later request, so the provider's prompt cache is rebuilt once.

Where Mework looks

Mework reads these files in this order, so the most specific come last:

• Project instructions come from workspace 1 only; the conversation's other workspaces add no instruction files.
• Folders above the repository's top level, or above the workspace outside a repository, are never read. To reuse a file from higher up, import it with @.
• CLAUDE.md, AGENTS.md and .claude/ are not read. To reuse one, import it from a MEWORK.md with a line such as @AGENTS.md.

Rules for some files only

A file in a rules/ folder can limit itself to some files with a paths: list in its front matter:

---
paths:
  - "src/**/*.ts"
  - docs/
---
Use the logger from src/log.ts, never console.log.

Such a rule is sent once the model opens a matching file with the read tool, and stays for the rest of that run. Patterns are relative to the workspace and case-sensitive; * stays within one folder, ** crosses folders, {a,b} matches either, a trailing / covers a whole folder, and a pattern without / matches the file name anywhere.

Instruction files in a sub-folder load the same way, once the model reads a file inside that sub-folder.

Import other files

Any instruction file can pull in another file with @ and a path:

Follow the style guide in @docs/style.md.
@"notes/release checklist.md"

Paths are relative to the file that contains them, or absolute; ~ and URLs do not work, and imports nest up to 4 levels deep.

An imported file is read wherever it is, inside the workspace or not: you named it. In the conversation it counts as a file of its workspaces, whichever workspace's instructions import it, so the security level treats it as one (see Security levels). The sandbox does not widen for it.

Limits and skipped files

A file can be up to 256 KiB, and all instruction files together up to 1 MiB and 256 files. A file is skipped whole when it is over a limit, is not valid UTF-8, or looks like it contains a secret such as a private key, an API token or a password. When Mework skips a file, it tells you in the app which one and why.

HTML comments (<!-- … -->) outside code blocks are removed before sending, so you can leave notes the model does not see.

Long-term memory

Long-term memory is a set of Markdown files the model reads and writes itself, so what it learns in one conversation is there in the next. There is one global memory, shared by every conversation on this computer. Project memory belongs to each workspace: it lives in the workspace's own folder and is shared by every conversation that has that workspace.

~/.mework/memory/             global memory
  MEMORY.md                   index: Mework maintains it
  <topic>.md                  memory documents: the model writes these
<workspace>/.mework/memory/   a workspace's project memory, same layout

A memory document can be up to 256 KiB and MEMORY.md up to 64 KiB; a larger file is left out whole. The lock file Mework uses while writing memory never shows up as a change in your repository.

Turn it on

Open More options → Conversation settings → Advanced tools and turn on Enable global memory, Enable project memory or both. Each switch adds that tier's index and memory tools, which are not listed on the Tools page; Enable project memory covers all of the conversation's workspaces. The switches belong to the conversation and are saved in presets; the built-in mework preset turns both on. After the first request, a switch can turn orange or gray; see conversation settings.

MEWORK.md files are project instructions, not memory: they are sent whether or not memory is on.

How the model uses it

At the start of each run, Mework sends the MEMORY.md of each tier that is on, global first: one line per document with its description. With more than one workspace, each workspace's index comes under its own heading, Project memory of workspace N (<path>), and the project memory tools take an optional workspace number saying whose memory to use (default 1); with one workspace they have no such parameter. The memory tools, such as create_project_memory, let the model read a document by name, create one, or replace a passage in one; no tool deletes, lists or searches memory. The index is read once per run, so a new document shows up from the next run.

• Every write to global memory asks for approval, even at Full access, and a hook cannot approve it. The card says the change affects memory shared by every project and has no Always allow. Project-memory writes and all reads do not ask.
• Plan mode does not hold back memory writes.
• A subagent without a role follows the conversation's memory switches; one with a role gets no memory tools.

Edit or clear memory yourself

Edit the files in any editor; changes apply from the next run.

• Change a memory: edit memory/<topic>.md.
• Remove a memory: delete memory/<topic>.md. From the next run the model no longer sees it in the index, even if you leave MEMORY.md untouched.
• Clear a tier: delete its memory/ folder.
• Keep your own text out of MEMORY.md: each memory write rebuilds it from its index lines and drops everything else. Standing instructions go in MEWORK.md.

Remote, worktree and temporary workspaces

• On an SSH machine or in WSL, instructions and memory work as in a local folder: Mework reads the remote folder's instruction files, and project memory lives in its .mework/memory/ on that machine, shared by every conversation that has that workspace.
• In a Git worktree, the worktree is its own top level: Mework reads the worktree's instruction files, not the project folder's, and adds your untracked MEWORK.local.md from the project folder. Project memory stays in the workspace's own .mework/memory/, not the worktree's, so it outlives the worktree.
• In a temporary workspace, Mework reads the administrator file, your ~/.mework files and the temporary folder. Project memory belongs to that one conversation.

Handoff notes

When the context reaches the auto-compact threshold, the model writes handoff notes and continues in a new conversation, <title>-handover-1, that starts from the notes, not the history.

Notes are stored in handoffs/<conversation>/ in Mework's app data folder, indexed in HANDOFF.md, and are deleted with their conversation. Each continuation works on a copy, so a chain of handoffs keeps editing one set.

What else Mework sends

Every request starts with Mework's system prompt sections, rebuilt each run: an environment block (working directory, platform, OS version and date), and sections for the selected skills, MCP servers and hooks.

Next comes the conversation's own system prompt: a System prompt card at the very top of the timeline, such as the engineering-practice prompt of the built-in mework preset. A System prompt card inserted further down applies from that point on: as a mid-conversation system message on models that accept one, otherwise the way plan-mode guidance arrives.

A prompt profile can reword most of Mework's own text; More options → History shows what each request carried.