/memesh

name: memesh
description: Use MeMesh to remember, recall, and manage AI knowledge across sessions, and to exchange task-focused messages with local agents. Triggers when the user asks to remember something, recall past decisions, forget outdated info, learn from mistakes, analyze work patterns, contact another agent, or handle a memesh_message or memesh_message_notice notification. Also triggers when the user asks "what do you remember", "where did we leave off", or wants to catch up on a project; when a session starts and project context is needed; and proactively when you make important decisions, fix bugs, learn lessons worth preserving, or owe another agent a requested result or disposition.
user-invocable: true

MeMesh — AI Memory Management

Persistent memory for AI agents. Load the saved project context at session start so decisions and relevant work history need less rediscovery; verify any handoff against current files and the user's request.

How to Access (auto-detect)

1. MCP tools available? (remember, recall, forget, learn in your tool list)
   → YES: use MCP tools directly (fastest, structured I/O)
   → NO: continue to step 2

2. CLI available? Run: memesh status
   → Works: use CLI commands below
   → "command not found": Run: npx @pcircle/memesh status
   → Works: use npx @pcircle/memesh <command> for all commands below

All examples below use CLI. MCP tools accept the same parameters as JSON objects.

Over MCP, `remember`, `learn` and `recall` also take `project`: a project id, or `false` for a memory that belongs to no project. Omitted, the call uses the project the session is bound to (the client's workspace root, or `MEMESH_PROJECT_ROOT`); a call that needs a project and finds none is refused with `workspace_unavailable`.

All 12 MCP tools

| Tool | Purpose | |---|---| | `work_package` | Prepare one bounded untrusted `digest` (calendar cluster) or `transcript` package from the newest Claude Code session under the client's single matching MCP workspace root; submit exactly one strict result or defer. Submit only stages pending human review and retains bounded redacted source turns for comparison; agents cannot apply or reject. No hidden reasoning, raw transcript, transcript path, API key, LLM, embedding, or vector data is exposed or used; hashes identify freshness and workspace scope rather than authentication. | | `remember` | Store knowledge as an entity with observations, tags, and relations; `note` (free text) derives title/observations/name; `replace: true` rewrites a named memory, keeping history; a new decision, or a `replace` of one, needs `why` | | `recall` | Search stored knowledge, list recent memories, or retrieve up to 20 exact IDs; keep `ids` separate from query, tag and cross_project | | `forget` | Archive an entity or remove one exact observation | | `export` | Export memories as portable JSON | | `import` | Import a JSON export with the required skip, append, or overwrite strategy | | `learn` | Record a structured lesson with error, fix, root cause, and prevention | | `task_state` | Read or update user-stated goal, next step, blocker, and finished work | | `briefing` | Assemble the current project's work topology — an eligible handoff precedes ranked memories at every level, after optional repository facts; `minimal` then shows decisions, lessons, knowledge and recent activity plus memories with no project, `standard` adds fresh task state and a capped durable-memory index, and `full` adds other projects and global memory | | `user_patterns` | Analyze work schedule, tool preferences, and focus areas | | `improvement` | Propose an evidence-linked product improvement or read its status; only a human may accept or reject it | | `message` | Discover live agents in one project, then contact one exact recipient with a bounded, untrusted payload. Native size and availability failures are distinct; acceptance, discovery, polling, and fetching do not acknowledge |

The Loop

Five moments. Everything else in this file is detail.

**SESSION START → load the briefing (once).** Call the `briefing` MCP tool or run `memesh briefing`. An eligible handoff from the same project appears ahead of ranked memories at every level, after optional repository facts; check its age and verify its claims before acting. The rest of the work topology covers decisions and direction, lessons not to repeat, what is known, and recent activity always; where the work was left off (goal / next / blocked / done) too at `standard`/`full` (not at the `briefing` setting's default, `minimal`). One call is cheaper than re-exploring the repo to reconstruct the same picture. `memesh briefing --index` returns only the index of durable memories — what is known here, one line each, without the ranked sections. Recent project decisions take priority over routine activity, and up to five project lessons are selected separately. The handoff, displayed task state, ranked memories, global memory at `full`, and injected index share a 4000-character memory-block limit. The standalone index keeps its own 40-line / 3072-byte caps and can show more than the index inside a crowded briefing; use `recall` for omitted memories and `memesh task` for the complete stored task state. Generic briefing does not report unread durable messages: it has no recipient identity. The session-start hook and each prompt do report them, but only when the session declared who it is by starting with `MEMESH_RECIPIENT=<id>`. If you already know the exact logical recipient, pass `recipient` with `project` (MCP) or use `memesh briefing --project <name> --recipient <id>`. The scoped line names the project and recipient and directs you to `message poll` first, then `message fetch` each returned `message_id`, then record `intake` for it (the session-start and prompt reminders can repeat until you do; fetching alone does not acknowledge). Length-limited briefing reminders can omit some project notices; the messa