m3-guide

Using m3 Memory

Tool names and signatures come from the MCP tool list. This is the part that isn't in a tool description: the protocol, and the traps.

Trust order

m3 memory > artifacts (git, handoff files) > session context. When m3 contradicts what you think you remember, trust m3 — context degrades across session boundaries, memory does not.

Verify capture is live

Registered ≠ working. The server can be connected while chatlog capture is silently dead. Call chatlog_status once early in a substantive session. If hooks are off or last_write is null/stale, say so loudly and don't proceed silently — a dead chatlog means this session's decisions vanish at the next session boundary. Never degrade quietly to flat files.

Protocol

• Search first. memory_search before re-deriving anything about this user, project, or machine. A settled decision re-litigated is a bug reintroduced.
• Write as you go. If it took effort to learn and will matter later, memory_write it — decisions, corrections, runbooks, preferences.
• Update, don't duplicate. Search before writing; prefer memory_update or memory_supersede (retires the old claim with a supersedes edge, keeps history) over a near-duplicate. Duplicates degrade later retrieval.
• Link. Reference related memories as [[name]] so memory_graph traversal stays useful.

Chat log

Captured turns from host agents live in a store separate from curated memory. Reach them with chatlog_search, chatlog_list_conversations, and chatlog_promote (promotes turns into curated memory).

⚠️ Never open a database file directly

The chat store and main store may be two databases, one unified database, or PostgreSQL — a deployment choice only the tools know.

Querying agent_memory.db for type='chat_log' returns zero rows on a split deployment even when capture is perfectly healthy — a false emergency. On a PostgreSQL primary there's no local file at all. Use chatlog_status; m3 chatlog status --json reports unified: true|false if you need the topology.

Scoping

Passing conversation_id, agent_filter, user_id, or scope enforces the filter strictly: an empty result means nothing matched in that scope, not that the store is empty.

More

Only some tools load at startup — tools_list_domains / tools_load_domain reach the rest (100+ in total). Health: m3 doctor, m3 chatlog doctor. Full reference: docs/AGENT_INSTRUCTIONS.md