Use a workspace as a folder

An ICM workspace is a folder. The method needs no server: the agent opens the entry file, follows it to the stage it is working on, and loads only what that stage lists. MemoryRelay keeps the reviewed versions; pull gives you the live one as plain files.

export MEMORYRELAY_API_KEY=mem_prod_xxxxx
npx -y @memoryrelay/mcp-server pull release-notes

Wrote .memoryrelay.json (binds this directory to release-notes).
Pulled release-notes (live 95689bb65b3d): 7 files into .icm/release-notes/
Start at .icm/release-notes/CLAUDE.md.

The agent (Claude Code, Codex, anything that reads files) now walks .icm/release-notes/ natively. No MCP connection is needed for that.

What pull does

• Resolves the workspace (by slug or id) among those the key can read, and its live version.
• Downloads that version through the release export and checks every file against the release's own listing (SHA-256). If anything differs, nothing is written.
• Writes the files, plus manifest.json and a .memoryrelay-pull.json stamp (the version and each file's hash), into .icm/<slug>/ or --dir. The new copy is written beside the old one and swapped in, so a failed pull leaves the previous copy intact.
• Writes a .memoryrelay.json binding in the current directory if there is none (it never overwrites one):

{
  "version": 1,
  "api_url": "https://api.memoryrelay.net",
  "workspace": { "id": "…", "slug": "release-notes" },
  "channel": "live",
  "route": null,
  "dir": ".icm/release-notes"
}

Options

Option
--route <id>	Check that the route exists in the live version, record it, and say where it starts (a route is a row of the entry file's "Route by what just happened" table)
--dir <path>	Where to write (default .icm/<slug>)
--force	Replace a folder pull did not write, or one edited since it was pulled

Is my copy current?

npx -y @memoryrelay/mcp-server status

release-notes in .icm/release-notes is behind: local 95689bb65b3d, live 2c41e07d9a10.
Run: npx -y @memoryrelay/mcp-server pull release-notes

status reads .memoryrelay.json (or --dir), compares the stamp with the live version and hashes the files. It exits 3 when the copy is behind or was edited, so a script or a CI step can pull only when needed; --json prints the report for machines.

Pull never writes back

The folder is a copy of a reviewed version. Editing it changes nothing in MemoryRelay, and the next pull refuses to discard those edits unless you pass --force. Changes go where they are reviewed:

• Run outputs (the product of a stage) are written into a run, with icm_stage_write or PUT …/runs/{run_id}/artifacts/{path}, and a person approves them. See Connect an agent.
• Changes to the workspace itself (stage contracts, shared rules, the entry file) go into a draft that a person checks and publishes as a new version.

From an agent

An agent connected over MCP can ask for the command itself: icm_pull {workspace: "release-notes"} returns the live version, the export route, the pull and status commands and the entry file to start from.

Offline checks

The folder carries manifest.json, so the walk checks run with no service:

python -m app.icm.cli walk-test .icm/release-notes

(from a checkout of the MemoryRelay API).