Mnemos

mnemos

Overview

You have a persistent memory layer available via the mnemos_* MCP tools. By default you will skip these tools on plain editing tasks. Don't. Mnemos is the learning-loop primitive for the project you are working on: corrections, decisions, and conventions compound across sessions if you record them. Silently editing leaves the store empty and the next session blind.

There is a known correction already stored about this exact failure mode: "agent skipped mnemos_session_start on editing tasks — LLMs skip optional tool calls when the task looks like plain reading/editing; the agent needs an external nudge." This skill is that nudge.

Prerequisites

• The mnemos binary is on PATH. mnemos doctor reports green for binary, config, storage, and each agent registration.
• mnemos init has wired the MCP server into your agent host (Claude Code, Claude Desktop, Cursor, Windsurf, or Codex CLI).
• The mnemos_* tools are visible this session. If they are not, the MCP server is not connected — see Error Handling.

Instructions

Session lifecycle

Start. The Claude Code SessionStart hook runs mnemos prewarm, which opens a mnemos session by default and injects a mnemos_session_id: line into context. If that ID is present, reuse it for session_id fields and do not call mnemos_session_start again. If no ID is present (manual MCP setup, non-Claude client, or hook disabled) and you are about to do real work, open one:

mnemos_session_start(
	project="<repo name from git or cwd>",
	goal="<one short line — what you are trying to do this session>"
)

Without a goal, the UserPromptSubmit hook backfills the first real prompt when available. With a goal, the session becomes a durable record that mnemos replay and future prewarms can use.

End. When the user signals done ("ship it", "that's it", "commit and close", "we're done"), close the session:

mnemos_session_end(
  session_id="<id>",
  summary="<one or two sentence recap of what shipped>",
  status="ok"
)

Status values: ok | failed | blocked | abandoned. An open session with no summary is dead weight in the next session's prewarm.

Which tool for which signal

What not to do

• Don't call mnemos_save for ephemeral within-session context ("I'm reading X now"). Save things worth remembering next session, not running commentary on this one.
• Don't call mnemos_correct for trivial typos or one-off slips. Corrections are for conceptual mistakes that would repeat.
• Don't fabricate tool arguments. Derive project from the git remote or the working directory; if unclear, ask.
• Don't spam mnemos_search before every edit. It is fast but the goal is a richer memory, not a pre-check ritual.
• Don't skip mnemos_session_end. Check for open sessions via mnemos_stats at the top of a session; if one is open from a past run, close it.

Rumination: when a stored rule looks wrong

Mnemos flags stored knowledge whose effectiveness has fallen below the threshold. These are rumination candidates and they want a hostile review, not a rubber stamp.

Trigger situations where you should check the queue:

• At the top of any long or consequential session (run mnemos_ruminate_list).
• When the user questions a rule the memory layer is surfacing ("is this still true?").
• When you just watched a saved skill or convention fail in practice.

Workflow:

1. mnemos_ruminate_list → returns {candidates: [...], counts: {...}}. Pick one by ID.
2. mnemos_ruminate_pack(id) → returns a review block with Hypothesis, Disconfirming evidence, Falsifiable restatement, Hostile review prompts, and an Action section. Read the block. Answer the hostile prompts honestly. The prompts are ordered: steel-man the opposite → find the fatal flaw → decide falsification vs noise → check whether context shifted → state the new prediction.
3. Decide one of two outcomes:
   • Resolve with a concrete revision: mnemos_ruminate_resolve(id, resolved_by, why_better). resolved_by is the ID of the new skill version or superseding observation. why_better must be a sentence naming a new prediction the revision makes that the old version did not — Popper's falsifiability guard. Cosmetic rewording is rejected by the server (min 16 chars, but length is not the real test — the test is whether you can state a new prediction).
   • Dismiss with an honest reason: mnemos_ruminate_dismiss(id, reason). Use when the hostile review convinced you the rule stands and the evidence was a one-off. The reason is preserved so a future rumination pass doesn't re-raise the same flag without context.

Never close a candidate silently or with filler. A rumination that resolves to "no change" is either a dismissal with a real reason or a bug in the monitor — both belong in the provenance trail, not in the void.