@embodied/memo

The Memo thin client: one command in a git clone joins the repo's shared reasoning workspace, ingests the code graph, and wires the memo MCP server into your harness — whichever harness that is.

Memo is a shared memory substrate for agent fleets — agents write typed, verification-gated items as they work; any agent on any model reads them back through a compressed lens instead of recomputing. Docs and evidence: memobench.com.

Install

npm install -g @embodied/memo

Join your repo's workspace

Run inside a git clone — the origin remote is the workspace join key. Teammates run the same command with their own key and land in the same workspace.

memo init --gateway https://api.memobench.com --invite <code>

That redeems the invite (fresh API key, saved show-once to ~/.memo/config.json, mode 0600 — never in the repo tree), resolves the repo's shared workspace, ingests the code graph, and writes .mcp.json.

Already have a key? memo init alone. Joining a teammate's existing workspace across billing accounts? memo init --join <workspace join code>.

Pay-as-you-go (x402) — opens with public launch

An agent with a USDC wallet can fund a metered key with one signed deposit, no login:

MEMO_WALLET_PRIVATE_KEY=0x… memo init --pay --usd 5

The wallet key is env-only by design. A wallet's first deposit mints the key (shown once and saved); top-ups never rotate it; --pay --recover rotates a lost key.

Commands

| Command | What it does | |---|---| | memo init | Join this repo's shared workspace, ingest the code graph, wire your harness | | memo sync | Re-ingest after commits/merges (no-op when HEAD is unchanged) | | memo pipeline create/list | Group dev/staging/prod mirrors of one product onto one shared workspace — guided by default (see Multiple repos) | | memo mcp | Run the stdio MCP server (launched by your harness) | | memo statusline | One line of reuse savings + balance for a status bar (Claude Code wired by memo init; cached ~60s) | | memo usage | Local per-model usage rollup (today/week/all-time) with memo's savings joined — the usage half never leaves your machine (see below) |

Multiple repos

Each repo gets its own workspace by default: the binding key is (your billing account, the normalized origin remote), so distinct repos never mix, and every teammate who runs memo init in a clone of the same repo lands in the same workspace. One machine-global key in ~/.memo serves all of them.

Big repos. Ingest is capped at 3000 .ts/.tsx files per call. Over the cap, memo init completes everything except the ingest and tells you to re-run with --include <path-prefix> (repeatable) — e.g. memo init --include gateway --include web. Put the chosen prefixes in your repo's onboarding notes so teammates ingest the same scope.

Related repos (pipelines). When several repos are one product — dev, staging, prod mirrors, or modularized halves of one codebase — group them so reasoning items compound across them instead of being re-derived per repo. Run the guided setup from any clone; it prompts for the name and member repos, shows the plan, and creates nothing until you confirm:

memo pipeline create

Scripts and agents use the explicit form:

memo pipeline create myproduct \
  --repo [email protected]:acme/product-dev.git  --environment dev \
  --repo [email protected]:acme/product-prod.git --environment prod
memo pipeline list

All grouped repos share ONE workspace: a decision recorded while working dev is in the lens when the team works prod. Each repo's code graph stays scoped to its own repo (ids are namespaced per repo, and memo_retrieve serves the launch repo's slice), so even mirrors with identical file layouts don't collide. Notes are stamped with the originating repo and environment label automatically.

Membership is always explicit. Only repos you list are grouped — nothing is inferred from similar names, shared layouts, or fork history. A fork or subset repo is NOT a pipeline member even when it resembles one: it keeps its own workspace (see CROs below for one-off transfers). And a repo that already has its own workspace or pipeline is never folded in silently — the gateway refuses until the guided setup's consent question (or --allow-rebind in scripts) says yes, so a mistaken listing can't hijack an established workspace. Tip: create the pipeline before running memo init in the clones and the question never comes up.

Two operational notes: creating a pipeline rebinds the listed repos, so other clones should re-run memo init (no flags, idempotent) to pick up the shared workspace; and every clone of the grouped repos needs client ≥0.1.6 — older clients sync unscoped graphs that collide across repos.

Undo. memo pipeline remove <remote> (no argument = the clone you are standing in) takes a repo back out: it returns to the workspace it held before the fold-in — remembered at fold-in time — or simply unbinds if it joined fresh, and the next memo init mints its own workspace. memo pipeline delete <name> dissolves a whole pipeline the same way and frees the name. Both move only FUTURE items: everything banked while grouped stays in the shared workspace, nothing is deleted.

One-off transfers (CROs). For repos that don't belong in one pipeline, carry reasoning across as a frozen bundle instead of a shared lens: memo cro export in the source clone prints a bundle id (--publish to make it readable across billing accounts; default is private to you and that workspace's members), and memo cro import <bundleId> in the target clone lands it as typed items + edges with lineage. Same-workspace re-imports are rejected, so you can't double-apply a bundle to its own source.

Local usage stats (nothing is uploaded)

memo usage answers "how much of my usage did memo save?" across sessions and time windows — with the sensitive half never leaving your machine.

While Claude Code renders the memo statusline, the client keeps a per-session, per-model token ledger under ~/.memo/harness-usage/ — plain JSON files on your disk, owned by you, deletable with rm. memo usage rolls them up:

$ memo usage
              today         week     all-time   memo saved
  fable   68.2k out   412.7k out     1.9M out   ~74.3k all-time (~4%)
  opus            —    88.4k out   301.2k out   ~2.1k all-time (~1%)

  sessions: 3 today · 14 this week · 41 ledgers (380 KB, oldest 2026-07-12)
  denominators: local only (~/.memo/harness-usage — never uploaded); ...

The denominators — your overall per-model token usage — are local-only: there is no upload path of any shape, and Memo's servers cannot reconstruct them. The savings column is memo's own product data (reuse of memo items, clamped estimates) from GET /v1/usage/summary; the join happens on your machine, at render time. That's also why the portal has no such view: the % lives where the data lives.

Retention is your knob, not ours: memo usage --prune 30d deletes ledgers idle longer than 30 days — and because there is no server copy, deletion is complete by construction. Set {"usage": {"retainDays": 30}} in ~/.memo/config.json to prune automatically (~daily). The default is keep forever: it's your disk and your history. --json for scripts; --offline skips the gateway entirely (the savings column disappears, the local table always works).

Honest caveats, also in memo usage --help: figures cover this machine's statusline-fed sessions only (other harnesses are invisible, so the % can overstate); sessions bucket whole into windows by last activity; ~ marks clamped estimates; % compares saved decode tokens against the same model's actual decode tokens, never mixed models.

Harness wiring

memo init writes the config each harness actually reads, and a short marker-delimited usage block into the instruction files it consults — the block is what makes sessions call the tools at session/task start instead of leaving adoption to chance. Re-running init refreshes both in place.

| Harness | MCP config | Instruction file | |---|---|---| | Claude Code, Cursor, .mcp.json readers | .mcp.json (written always) | CLAUDE.md | | OpenAI Codex | .codex/config.toml (written when Codex is detected; loads once you trust the project) | AGENTS.md | | Hermes (Nous Research) | paste-ready snippet for ~/.hermes/config.yaml printed on detection | AGENTS.md / HERMES.md | | OpenClaw | paste-ready snippet for ~/.openclaw/openclaw.json printed on detection | its workspace AGENTS.md (see snippet) | | Buzz (buzz.xyz) | nothing to do — Buzz spawns your harness with its own config intact, and its native agent reads AGENTS.md | AGENTS.md |

The API key never enters any of these files — it stays in ~/.memo/config.json, which also makes the server work under harnesses that strip inherited env vars from MCP subprocesses (Buzz's native agent does exactly that; HOME survives, so the file is found).

MCP tools: memo_context (the compressed working set at session start), memo_note (write a typed item — it enters verification, not just storage), memo_retrieve (code-graph retrieval on demand).

Config: ~/.memo/config.json, or MEMO_GATEWAY_URL / MEMO_API_KEY env vars. MEMO_WORKSPACE_ID + MEMO_REPO_REF (set together) pin a workspace explicitly when the harness launches outside the repo.

License

Proprietary — see LICENSE.md. Published so customers and their agents can access the Memo service.