Memory and code search for your agents
How a team's agents share what they learn in Git, find code through one call, and reach both over MCP, with the limits, the plans and the off switches.
At a glance
- Each mux workspace has one shared memory repo and one private repo for each member. Both are private Git repos on mux.
- Agents read and save through one tool, workspace_memory. Each save is a Git commit, checked against the repo's current revision, so two agents can't overwrite each other.
- get_context returns the code evidence for a task with the relevant memory beside it. Memory takes at most a third of the packet.
- Other agents reach the same index and memory through mux's MCP server. The MCP servers you add to muxcode serve only tasks on your Mac.
An agent that starts each task from nothing relearns the same lessons: how this team deploys, which test is flaky, what you asked for last week. mux gives a team’s agents two things that last between tasks: memory they write themselves, and a search over the team’s code. This post covers how both work, for agents in muxcode, in the cloud sandbox, and in other tools over MCP.
Two Git repos per workspace
Each mux workspace has one shared memory repo for the whole team, and each member has a private repo of their own. Both are private Git repos that mux keeps in Cloudflare Artifacts. They are not GitHub repositories, and a workspace can use memory before it picks any code to index.
workspace_memory one tool, seven operations Whose private repo a call reaches comes from the credential: the member signed in to muxcode, the member who started a cloud task, or the workspace owner who made the key an MCP client uses. No tool takes a workspace, a member or a key as an argument. muxcode refuses a call that tries to name one.
Saves go to the private repo unless the agent names the shared one. Personal preferences stay private; lessons the team can reuse go to the shared repo. Moving something private into shared memory takes an explicit choice.
MEMORY.md is the map
Each repo starts at MEMORY.md: a short page of context with an ## Index section of links to topic files. A link is [[path]] from the repo’s root, without the .md.
# Memory
Deploys go through staging first.
## Index
- [[deploy]]
- [[testing/e2e]]
A topic file holds lessons as short Markdown bullets, each with its source and the date it was added. When an agent saves a new file, mux links it from MEMORY.md once, unless the map already reaches it through a linked page. It never rewrites a map an agent edited.
| Limit | Size |
|---|---|
MEMORY.md |
8 KiB |
| Any other file | 64 KiB |
| One repo | 256 files and 2 MiB |
An edit that would break a limit gets 413 memory_limit. A full MEMORY.md never stops a new file from saving: the file saves, and the reply carries a memory_unlinked notice so the agent can link it from a topic page instead.
What an agent saves is context, not orders. Saved text never grants a permission or overrides the current task.
One tool, seven operations
Agents use memory through one tool, workspace_memory. Only write and append change anything.
| Operation | What it does |
|---|---|
status |
Shows the repo’s revision and its MEMORY.md. |
list |
Lists the files under a path, up to 256 at the API. |
read |
Reads a file. |
search |
Finds the passages that match a query: 8 by default, up to 50. |
write, append |
Replaces or extends one file, as one Git commit. |
history |
Lists a file’s commits: 20 by default, up to 50. |
There is no delete. An agent revises an old entry in place, and Git keeps every earlier version.
How an edit commits, and how two edits conflict
An edit names the file, its content, the repo’s current revision, a fresh mutationId and a source. mux commits and pushes before it answers, and each saved edit returns its new revision.
The revision check covers the whole repo, not one file. If anyone saved since the agent read, even to another file, the edit gets 409 memory_conflict with the current revision. The agent reads again, merges, and sends a new edit with a new ID. A lost reply never turns into a blind overwrite.
r1 r1 too deploy.md, revision r1 testing/e2e.md, revision r1 r2, merges, writes again with a new mutationId mutationId mutationId returns the commit it already made.A mutationId is for an exact retry only. The same ID with the same edit returns the commit it made the first time. The same ID with a different edit gets 409 mutation_conflict.
Who can save
Reading needs access to the workspace. Saving needs at least the agent role, so a viewer reads but can’t save. mux checks membership, the grant and whether the key was revoked on every call.
In muxcode, saving needs no permission card. Plan mode only reads memory, and so do read-only subagents. In a workflow, only the worker seat saves; every other seat reads.
What loads at the start of a task
When a task starts in a workspace signed in to mux, muxcode fetches both MEMORY.md files, shared and private, and hands them to the agent. It waits at most 5 seconds and cuts each to 12,000 characters. If mux doesn’t answer in time, the task starts anyway.
A cloud task reads both files on mux while it starts, so they are ready for its first turn, and cuts each to 4,000 characters. From there, the agent searches memory and follows links as it needs them, and saves lessons as it works, not a summary at the end.
What get_context packs
get_context answers a task, not a query. One call returns one packet of evidence from across the workspace’s indexed repositories:
- passages, each tied to the commit it was read at;
- the files two hops out on the code graph: imports, tests, and the routes one repository calls in another;
- findings a workspace owner approved;
- relevant notes from shared memory and the caller’s private memory.
The packet has a budget, 6,000 by default, and a caller may ask for 1,024 to 16,000. mux counts it in UTF-8 bytes, an upper bound on tokens.
- Findings a workspace owner approved
- The head of each
MEMORY.md, shared and private - Up to five memory hits a scope, taken in turn
- Code evidence by rank, with its graph edges
Memory arrives in its own field, agentMemory, marked authority: "agent-authored" with its scope and Git revision. Approved findings stay in their own field, and code stays in evidence. What memory couldn’t supply, because it was warming up, cut short or over budget, is named in omissions, never passed off as an empty search.
Words and meaning
Search by words works on every plan. It scores windows of 8 lines by how often the query’s words appear.
Search by meaning needs Pro, Pro+ or the trial, and index hours left this month: 30 for each workspace, shared with the code index. Past them, memory search matches words. The first search by meaning on a new revision can answer memory_index_warming; the agent retries after the interval it names. Meanwhile get_context uses word matches and says the meaning search is missing.
Shared and private memory sit in separate search indexes, and ordinary code search never lists private memory files.
Personal stays personal
Private memory joins a get_context packet only for a caller that can prove whose it is:
| Caller | Private memory |
|---|---|
| A task in muxcode on your Mac | yes, yours |
| An agent on mux’s MCP server | yes, that of the owner who made its key |
| A cloud task | yes, its starter’s, through a memory ticket made for that task |
| An older client | no: shared memory and approved findings only |
A cloud task’s ticket is good for at most 35 days. Each call checks that the task is still running, that its key is live and that its member still has access. Workspace membership alone grants no access to someone else’s task or private memory.
Old project notes move in
Before memory, muxcode kept project notes on your Mac. At the start of each task in a signed-in workspace, except in Plan mode, muxcode copies them into your private repo under legacy/ and a 12-character folder for the project, in small batches, in the background. Each copy keeps its content and a reference to its old revision.
The originals on your Mac never change. A note too large for memory stays on your Mac. Once the workspace is signed in, the agent saves to memory instead of project notes.
Without a mux sign-in, workspace_memory reads your old project notes and saves nothing.
Two sides of MCP
MCP links agents to tools, and muxcode has it in both directions. mux runs an MCP server that gives other agents the code index and memory. muxcode, in turn, runs MCP servers you add, for its own tasks.
mux’s MCP server
Codex, Claude Code and Copilot CLI reach https://usemux.com/mcp with a workspace key sent as Authorization: Bearer hk_live_…. A workspace owner makes the key in mux under Access keys, in the sidebar. The key names the workspace, so no tool takes one, and private memory is that of the owner who made the key. The MCP guide has each client’s setup.
On Hobby, search_code and ask_code answer plan_refused; the other seven tools work. Every call counts against the plan’s API limits.
muxcode doesn’t use this server. It reaches the code index and memory directly, through its own sign-in.
muxcode’s own MCP servers
Add a server under Settings → Personal → Integrations → MCP servers. It either runs on your Mac, by command, or is remote, at an https:// URL. muxcode keeps them in ~/.muxcode/mcp.json and never shows a stored key.
- A server on your Mac starts only after you press Allow once. muxcode asks each time the task’s agent starts, so a task you come back to after it sat idle asks again. Bypass mode doesn’t skip that card.
- Each tool call then asks on its own card, unless a rule you saved allows that tool.
- Plan mode starts no MCP servers.
- From muxcode 1.0.5, a cloud task is never offered them.
These servers need no plan and no mux sign-in.
Which plans get what
Memory needs a mux connection, not a paid plan.
| Hobby | Pro and the trial | Pro+ | |
|---|---|---|---|
| Shared and private memory | yes | yes | yes |
| Memory search | words | words and meaning | words and meaning |
| Index hours a month, per workspace | none | 30 | 30 |
| Repositories in the code index | 1, refreshed by hand | 20, on each push | 50, on each push |
| Memory in cloud tasks | no sandbox | Pro: 5 at once, 40 hours a month; trial: 1, 3 hours in all | 12 at once, 300 hours a month |
| mux MCP server tools | 7 of 9 | all 9 | all 9 |
| API calls, a minute and a month | 30 and 50,000 | 120 and 500,000 | 300 and 2,000,000 |
| muxcode’s own MCP servers | yes | yes | yes |
The trial is 72 hours of Pro. A team workspace takes its API limits and its repository count from the best plan among its members, a live trial counting as Pro. It gets search by meaning and refresh on push unless every member is on Hobby. Each member’s cloud tasks and Clef come out of their own plan, not a shared one.
How to turn each part off
| Part | Off switch |
|---|---|
| Hosted memory | No switch. Don’t sign the workspace in to mux, or choose Sign out on this Mac. Plan mode reads memory and saves nothing. |
| Memory in cloud tasks | Don’t start cloud tasks. |
| One of muxcode’s MCP servers | Settings → Personal → Integrations → MCP servers: turn its switch off, or press Remove. |
| mux’s MCP server, for one agent | Revoke its key under Access keys, in the sidebar. Its next call gets 401 unauthenticated. |
Without a mux sign-in, pi in muxcode runs on your Mac alone, with your model logins, project notes and history, and your own MCP servers.
The working where each number comes from
- Repos, scopes, the
MEMORY.mdformat, the seven operations, the revision check andmemory_unlinked:docs/markdown/memory.mdandapps/index/container/memory.py, read on 2026-10-07. - 8 KiB, 64 KiB, 256 files and 2 MiB:
MAX_ROOT,MAX_FILE,MAX_FILESandMAX_REPOinmemory.py. - 409
memory_conflictandmutation_conflict, and an exact retry returning the saved commit:_writeinmemory.py. - List up to 256, search 8 by default and up to 50, history 20 by default and up to 50:
apps/api/src/memory/contracts.tsandmemory.py; since moved topackages/types/src/memory-schemas.ts, read again on 2026-11-04. Word search over 8-line windows:lexicalinmemory.py. - 3 seconds, 12,000 characters, the legacy folder and its small batches:
src-tauri/src/memory.rsin muxcode 1.0.7, read on 2026-10-07. The wait has been 5 seconds (STARTUP_WAIT) since commitf35396d3of 22 October 2026, the 1.0.17 fixes; read again at commite8e813b2(muxcode 1.0.22) on 2026-11-04, still 12,000 characters. - 4,000 characters in a cloud task:
#loadStartupinapps/sandbox/src/agent/memory.ts, read on 2026-11-04. - Budget 1,024 to 16,000, 6,000 by default, the 512 held back, memory at most a third, packing order:
apps/api/src/routes/context.ts, read on 2026-10-07. Read again on 2026-11-04: the budget’s bounds and default arecontextTokenBudgetandcontextArgumentsinpackages/types/src/corpus-schemas.ts, and the packing ispackContextinapps/api/src/routes/context-packet.ts. Five hits a scope:apps/api/src/memory/recall.ts. The bar is the default budget; a real packet fills less when there is less to say. - 35 days:
MEMORY_TICKET_TTL_MSinapps/api/src/lib/memory-ticket.ts. - Nine tools and the Hobby refusal:
apps/mcp/src/index.tsandapps/docs/src/content/docs/mcp.mdx. - muxcode’s MCP servers:
src-tauri/src/mcp.rs,src-tauri/src/permissions.rsandsrc/components/settings/McpSettings.tsxin muxcode 1.0.7; the settings path fromSettingsPage.tsx. - Plans:
PLAN_LIMITS,PLAN_METERS,TRIAL_LIMITSandTRIAL_DURATION_MSinpackages/types/src/index.ts, anddocs/markdown/billing.md, read on 2026-10-07; the sandbox figures read again on 2026-10-28. A team’s best-plan limits:standingLimitsandorganizationPlaninapps/api/src/billing/, anddocs/markdown/billing.md, read on 2026-11-04; before then a team had Pro’s API limits.