Persistent memory sounds like the obvious fix for Claude Code's cold starts. It is not that simple. A memory layer can preserve the decision that saves a future session, or it can keep a stale workaround alive long after the code changed.
Mnemo is worth saving as an article seed because its source gives us the right engineering question: where should Claude Code draw the boundary between always-loaded instructions, recallable memories, auto-captured project facts, and explicit deletion?
Start with memory policy, not installation
The bundled /mnemo skill is the best place to read the intended contract. It says to call mnemo_recall before answering when prior context might help, to use mnemo_remember for non-obvious decisions or user preferences, and to avoid capturing transient task state. It also says not to store facts already carried by CLAUDE.md or other always-loaded files. That is the key adoption boundary. Keep stable repo rules in CLAUDE.md or AGENTS.md; use Mnemo for the long tail: why an integration is shaped a certain way, which migration pattern failed before, or what preference should follow the user across projects.
Install it in read-write stages
The README install path is concrete: npm install -g @mnemo-mcp/cli, then mnemo init, then mnemo doctor after restarting Claude Code. mnemo init installs the skill and MCP server; mnemo init --with-hooks also wires auto-capture hooks. Do not enable hooks first in a sensitive repo. Start with manual commands: mnemo remember "our API auth uses OAuth2 with refresh tokens every 30min", mnemo recall "what's our auth pattern?", mnemo list, and mnemo forget <id>. Once recall and deletion behave the way your team expects, consider hooks for decision files only.
The MCP surface is small but powerful
The server source exposes mnemo_recall, mnemo_remember, mnemo_forget, mnemo_list, and mnemo_stats. It also exposes procedure tools for suggesting and running stored workflows. Treat those as different risk classes. Recall and stats are read paths. Remember and forget change the memory set. Procedure suggestion can shape how an agent starts work. That means a team should review when Claude Code is allowed to write memory automatically, when it must ask, and when deletion needs an explicit user request. The skill already says mnemo_forget should be used only when the user asks or when a memory contradicts current reality; keep that rule.
Recall score is not truth
The README advertises semantic recall, and the ranker shows the actual shape: 0.7 similarity, 0.2 recency, and 0.1 access boost. Recency has a 30-day half-life, and access boost saturates at 20 reads. That is useful ranking, not proof. A high-scoring memory can still be outdated. A frequently read memory can become over-trusted. In a Codex-style workflow, the agent should quote the recalled memory, check the current files, and then decide whether the memory still applies. If a memory is wrong, replace it instead of adding a contradictory note beside it.
Hooks should index durable files only
With mnemo init --with-hooks, the README says post-edit capture watches CLAUDE.md, AGENTS.md, GEMINI.md, *.adr.md, docs/decisions/**, and docs/adr/**. That is a sensible default because those files are supposed to carry decisions. It is also a warning. If a team writes scratch notes into docs/decisions/, hooks can promote noise into memory. Before turning hooks on, clean up where decisions live. If the repo does not have reviewed ADR or decision folders, leave hooks off and teach memories manually with /teach or mnemo remember.
Secret guard is not a privacy strategy
Mnemo is local-first, with no daemon, cloud account, or telemetry according to the README. The architecture stores data through sql.js at ~/.mnemo/memory.db, and the core includes a secret guard for common GitHub, npm, AWS, OpenAI, Anthropic, Google, Slack, Stripe, JWT, and private-key patterns. That is useful, but it should not change the rule: do not store raw tokens, customer data, incident payloads, or private snippets as memory. Store the decision or procedure, not the secret that triggered it. A local memory database is still project data.
Procedures are the strongest use case
The newer procedural memory path is more interesting than generic facts. The CLI supports mnemo procedure record, list, show, run, done, suggest, and delete flows, with project, global, or team scope. The MCP server exposes mnemo_procedure_suggest and mnemo_procedure_run. That fits recurring agent work: release checklist, migration review, security triage, or a house style for bug reports. It is weaker for short-lived task state. If a procedure needs to survive, record the checklist and mark outcomes with mnemo procedure done; do not ask Claude Code to infer a process from scattered memories.
Save Mnemo as a memory-boundary article. It is valuable when Claude Code users separate durable knowledge from transient context, review write paths, and keep deletion as a first-class operation.
Practical takeaway
Install with npm install -g @mnemo-mcp/cli, run mnemo init, restart Claude Code, and verify with mnemo doctor. For the first week, skip --with-hooks: add three manual project memories, recall them during real tasks, and delete one with mnemo forget <id>. Turn on hooks only after your ADR and decision folders are clean enough to become memory.