All posts

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.

Callers
Ada's task on her Mac muxcode, signed in sharedAda's
Ada's cloud task its own memory ticket sharedAda's
Bola's agent in Claude Code mux MCP, a key Bola made as owner sharedBola's
On mux
workspace_memory one tool, seven operations
mux API checks role, size and the person behind the key
Index container commits and pushes, then answers
Private Git repos on mux
Workspace repo shared, the whole team
Ada's repoprivate private, only Ada
Bola's repoprivate private, only Bola
Every caller reaches the shared repo and the private repo of the person behind its credential. The index container commits and pushes each edit before it answers.

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.

Agent A, Ada's task Workspace repo Agent B, Bola's task
Agent A reads the repo at r1
r1
Agent B reads the repo at r1 too
still r1
Agent A writes deploy.md, revision r1
r2 saved
Agent B writes testing/e2e.md, revision r1
409 memory_conflict, head is r2
Agent B reads at r2, merges, writes again with a new mutationId
r3 saved
Agent B loses the reply and resends the same mutationId
r3 again, saved once
Agent B’s edit touches a different file from A’s and is still refused, because the check is on the repo’s head. Resending the same 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.

One packet, budget 6,000 (the default) allowed: 1,024 to 16,000
  1. Findings a workspace owner approved
  2. The head of each MEMORY.md, shared and private
  3. Up to five memory hits a scope, taken in turn
  4. Code evidence by rank, with its graph edges
Memory can take at most a third of the packet, so unreviewed notes can never crowd out the code a claim rests on. Room memory doesn’t use goes to code.

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, for other agents
Codex
Claude Code
Copilot CLI
usemux.com/mcp Bearer hk_live_…, one workspace
mux API code index and memory
workspace_memoryget_contextrecord_context_outcomecorpus_statuslist_repositoriesgrep_codetrace_code search_codeask_code
every plan Pro, Pro+ and the trial
muxcode skips this server it reaches the mux API through its own sign-in
muxcode's own MCP servers
A task on your Mac muxcode
Your MCP servers ~/.muxcode/mcp.json, by command or https URL
every plan, no sign-in needed a server on this Mac asks each time the agent starts each tool call asks, unless a saved rule allows it Plan mode starts none cloud tasks are never offered them
mux’s server serves other agents, and two of its nine tools need a paid plan. The servers you add to muxcode serve only tasks on your Mac, on every plan.

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.md format, the seven operations, the revision check and memory_unlinked: docs/markdown/memory.md and apps/index/container/memory.py, read on 2026-10-07.
  • 8 KiB, 64 KiB, 256 files and 2 MiB: MAX_ROOT, MAX_FILE, MAX_FILES and MAX_REPO in memory.py.
  • 409 memory_conflict and mutation_conflict, and an exact retry returning the saved commit: _write in memory.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.ts and memory.py; since moved to packages/types/src/memory-schemas.ts, read again on 2026-11-04. Word search over 8-line windows: lexical in memory.py.
  • 3 seconds, 12,000 characters, the legacy folder and its small batches: src-tauri/src/memory.rs in muxcode 1.0.7, read on 2026-10-07. The wait has been 5 seconds (STARTUP_WAIT) since commit f35396d3 of 22 October 2026, the 1.0.17 fixes; read again at commit e8e813b2 (muxcode 1.0.22) on 2026-11-04, still 12,000 characters.
  • 4,000 characters in a cloud task: #loadStartup in apps/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 are contextTokenBudget and contextArguments in packages/types/src/corpus-schemas.ts, and the packing is packContext in apps/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_MS in apps/api/src/lib/memory-ticket.ts.
  • Nine tools and the Hobby refusal: apps/mcp/src/index.ts and apps/docs/src/content/docs/mcp.mdx.
  • muxcode’s MCP servers: src-tauri/src/mcp.rs, src-tauri/src/permissions.rs and src/components/settings/McpSettings.tsx in muxcode 1.0.7; the settings path from SettingsPage.tsx.
  • Plans: PLAN_LIMITS, PLAN_METERS, TRIAL_LIMITS and TRIAL_DURATION_MS in packages/types/src/index.ts, and docs/markdown/billing.md, read on 2026-10-07; the sandbox figures read again on 2026-10-28. A team’s best-plan limits: standingLimits and organizationPlan in apps/api/src/billing/, and docs/markdown/billing.md, read on 2026-11-04; before then a team had Pro’s API limits.