/m0-remember — Write to the Operational Thread
The write path for M0. One call appends one entry to the shared thread for a
project. Writing the same content twice creates one row, so this is safe to call
after every step and safe to retry.
Quick Reference
M0="${M0_BASE_URL:-http://127.0.0.1:8787}"
M0S="$HOME/.claude/skills/m0/scripts"
# Over HTTP
curl -s -X POST "$M0/api/brain/checkpoint" \
-H 'Content-Type: application/json' \
-d '{"project":"acme-web","kind":"step_done",
"text":"Fixed the token refresh race in the auth middleware.",
"next_step":"Add a regression test for two concurrent refreshes.",
"last_verified":"pytest tests/auth -q: 31 passed",
"source_tool":"claude-code","meta_json":{"pr":42}}'
# {"id":"9a71de71…","ts":"2026-08-01T13:31:26.536Z","ok":true,"deferred":false}
# Without a server (same store, same guarantees)
python3 "$M0S/m0_server.py" write \
--project acme-web --kind step_done \
--text "Fixed the token refresh race in the auth middleware." \
--next-step "Add a regression test for two concurrent refreshes." \
--last-verified "pytest tests/auth -q: 31 passed" \
--source-tool claude-code --meta '{"pr":42}'
If the MCP tools are wired (/m0 mcp), call m0_remember directly instead — same
endpoint, fewer moving parts, and meta takes a real JSON object.
Fields
| Field |
Required |
What to put in it |
project |
yes |
The project key. Use one stable value per project — the repository or directory name is the usual choice. Getting this wrong splits the thread. |
text |
yes |
What happened, in one or two plain sentences. Written for a reader with no other context. |
kind |
no |
Defaults to step_done. See the table below. |
next_step |
no |
The single next action. Concrete enough to act on without re-deriving it. |
last_verified |
no |
What was actually checked, and how. A command and its result, not an impression. |
meta_json |
no |
Structured metadata as a JSON object, e.g. {"pr":42,"tests":"green"}. |
session_id |
no |
Session identifier, when known. |
source_tool |
no |
Which tool is writing. Fill it in — it is what makes the thread legible across tools. |
branch, head_sha |
no |
Version-control position. Worth including whenever the entry is about code. |
Kinds:
kind |
Use it for |
step_done |
A completed step, a fact, or a decision. The default. |
compact_checkpoint |
A session handoff — see /m0-handoff. |
session_end |
A session closing, usually from a hook. |
lane_dispatched |
Work handed to a subagent or parallel lane. |
lane_result |
The outcome of that work. |
ambient_signal |
Context observed rather than reported. |
An unknown kind is rejected with HTTP 400, deliberately: a typo would create a
category no reader looks in.
Procedure
Resolve the project key. Use $M0_PROJECT if set, otherwise the repository
or directory name. Reuse whatever earlier entries used — check with
/m0-recall if unsure. Do not invent a variant.
Write one entry per meaningful thing. A step that landed, a decision with
its reason, a verification result. Not a running commentary.
Include version-control context when the entry is about code:
BRANCH="$(git rev-parse --abbrev-ref HEAD 2>/dev/null)"
SHA="$(git rev-parse --short HEAD 2>/dev/null)"
Be honest in last_verified. Put the command and its actual result there.
If nothing was verified, leave it empty. A false verification claim in a
memory store outlives the session that made it and misleads every later reader.
Check the response. {"ok":true,"deferred":false} means it is durable.
"deferred":true means the store was busy and the entry is spooled to a
sidecar file — it is not lost and lands on the next drain or server start. Say
so rather than reporting a clean write.
Good and bad entries
text: "Fixed the token refresh race in the auth middleware: the retry
path double-incremented the nonce."
next_step: "Add a regression test for two concurrent refreshes."
last_verified: "pytest tests/auth -q: 31 passed"
text: "Made some progress on auth." # nothing to act on
next_step: "Continue." # not a next step
last_verified: "Tests should pass now." # a claim, not a check
Notes
- Idempotent.
id is a SHA-256 of the content fields, ts excluded. Re-writing
identical content returns the identical response and leaves one row. Retry
freely.
- Metadata is lenient. An object, a JSON string, or free text all work: a JSON
string is parsed and canonicalised, anything else is stored as
{"note": "…"}.
It never rejects what it could have kept.
- Local-only. SQLite on disk, loopback server, no outbound calls, no telemetry.
- Reading back:
/m0-recall. Handoffs: /m0-handoff. Plumbing: /m0.
1---2name: m0-remember3description: Write one entry to the M0 operational thread so the next session, in this tool or any other, can continue the work. Records a completed step, a decision, a verification result, or a dispatched lane. Idempotent and local-only. Triggers on: 'remember this', 'm0 remember', 'save to memory', 'log this decision', 'record what we did', 'note for next session', 'write a checkpoint'.4---56# /m0-remember — Write to the Operational Thread78The write path for M0. One call appends one entry to the shared thread for a9project. Writing the same content twice creates one row, so this is safe to call10after every step and safe to retry.1112## Quick Reference1314```bash15M0="${M0_BASE_URL:-http://127.0.0.1:8787}"16M0S="$HOME/.claude/skills/m0/scripts"1718# Over HTTP19curl -s -X POST "$M0/api/brain/checkpoint" \20 -H 'Content-Type: application/json' \21 -d '{"project":"acme-web","kind":"step_done",22 "text":"Fixed the token refresh race in the auth middleware.",23 "next_step":"Add a regression test for two concurrent refreshes.",24 "last_verified":"pytest tests/auth -q: 31 passed",25 "source_tool":"claude-code","meta_json":{"pr":42}}'26# {"id":"9a71de71…","ts":"2026-08-01T13:31:26.536Z","ok":true,"deferred":false}2728# Without a server (same store, same guarantees)29python3 "$M0S/m0_server.py" write \30 --project acme-web --kind step_done \31 --text "Fixed the token refresh race in the auth middleware." \32 --next-step "Add a regression test for two concurrent refreshes." \33 --last-verified "pytest tests/auth -q: 31 passed" \34 --source-tool claude-code --meta '{"pr":42}'35```3637If the MCP tools are wired (`/m0 mcp`), call `m0_remember` directly instead — same38endpoint, fewer moving parts, and `meta` takes a real JSON object.3940## Fields4142| Field | Required | What to put in it |43|-------|----------|-------------------|44| `project` | yes | The project key. Use one stable value per project — the repository or directory name is the usual choice. Getting this wrong splits the thread. |45| `text` | yes | What happened, in one or two plain sentences. Written for a reader with no other context. |46| `kind` | no | Defaults to `step_done`. See the table below. |47| `next_step` | no | The single next action. Concrete enough to act on without re-deriving it. |48| `last_verified` | no | What was actually checked, and how. A command and its result, not an impression. |49| `meta_json` | no | Structured metadata as a JSON object, e.g. `{"pr":42,"tests":"green"}`. |50| `session_id` | no | Session identifier, when known. |51| `source_tool` | no | Which tool is writing. Fill it in — it is what makes the thread legible across tools. |52| `branch`, `head_sha` | no | Version-control position. Worth including whenever the entry is about code. |5354Kinds:5556| `kind` | Use it for |57|--------|-----------|58| `step_done` | A completed step, a fact, or a decision. The default. |59| `compact_checkpoint` | A session handoff — see `/m0-handoff`. |60| `session_end` | A session closing, usually from a hook. |61| `lane_dispatched` | Work handed to a subagent or parallel lane. |62| `lane_result` | The outcome of that work. |63| `ambient_signal` | Context observed rather than reported. |6465An unknown `kind` is rejected with HTTP 400, deliberately: a typo would create a66category no reader looks in.6768## Procedure69701. **Resolve the project key.** Use `$M0_PROJECT` if set, otherwise the repository71 or directory name. Reuse whatever earlier entries used — check with72 `/m0-recall` if unsure. Do not invent a variant.732. **Write one entry per meaningful thing.** A step that landed, a decision with74 its reason, a verification result. Not a running commentary.753. **Include version-control context** when the entry is about code:7677 ```bash78 BRANCH="$(git rev-parse --abbrev-ref HEAD 2>/dev/null)"79 SHA="$(git rev-parse --short HEAD 2>/dev/null)"80 ```814. **Be honest in `last_verified`.** Put the command and its actual result there.82 If nothing was verified, leave it empty. A false verification claim in a83 memory store outlives the session that made it and misleads every later reader.845. **Check the response.** `{"ok":true,"deferred":false}` means it is durable.85 `"deferred":true` means the store was busy and the entry is spooled to a86 sidecar file — it is not lost and lands on the next drain or server start. Say87 so rather than reporting a clean write.8889## Good and bad entries9091```92text: "Fixed the token refresh race in the auth middleware: the retry93 path double-incremented the nonce."94next_step: "Add a regression test for two concurrent refreshes."95last_verified: "pytest tests/auth -q: 31 passed"96```9798```99text: "Made some progress on auth." # nothing to act on100next_step: "Continue." # not a next step101last_verified: "Tests should pass now." # a claim, not a check102```103104## Notes105106- **Idempotent.** `id` is a SHA-256 of the content fields, `ts` excluded. Re-writing107 identical content returns the identical response and leaves one row. Retry108 freely.109- **Metadata is lenient.** An object, a JSON string, or free text all work: a JSON110 string is parsed and canonicalised, anything else is stored as `{"note": "…"}`.111 It never rejects what it could have kept.112- **Local-only.** SQLite on disk, loopback server, no outbound calls, no telemetry.113- **Reading back:** `/m0-recall`. **Handoffs:** `/m0-handoff`. **Plumbing:** `/m0`.
coco-research