Best practices

Memory is only as useful as what goes into it. By the end of this page you will have:

1. a list of what your agent should save and what it should not;
2. rules for naming fact_key, working with sources and writing summaries;
3. a ready instruction to paste into CLAUDE.md or AGENTS.md.

What to remember

Save	Example
Decisions and their reasons	“Sessions live in Redis, not PostgreSQL: we need TTL and fast reads”
Team agreements	“Every change to migrations requires a review”
How to do things in this project	“staging is deployed through the app-staging systemd unit”
Root causes of bugs	“The import failure came from the cron time zone; fixed by setting TZ=UTC”
User preferences	“The user wants answers in English, without emoji”
Facts from documents — with the source	“API v2 returns dates in ISO 8601” + source_id: docs/api.md

What not to remember

• Secrets. Keys, tokens, passwords, connection strings. Memory Guard replaces them with placeholders, but do not treat that as your main defence: a secret does not belong in memory, not even as a placeholder.
• Raw dumps of chats and logs. A long piece of conversation is noise: hard to search and impossible to check. Session history exists for archiving; put conclusions into memory.
• What is easy to read from the code. Function signatures and directory layouts go stale at the first refactor.
• Temporary state. “A test is running now”, “branch feature-x is not merged” — an hour later it is false.
• Other people’s personal data without need and consent.

How to word a record

• One fact per record. Then it can be updated, deleted or flagged on its own.
• Self-contained. Not “as agreed, we do it this way” but “staging is deployed through the app-staging systemd unit”.
• Use the words people will search for. Search relies on the words in the record text, so spell them out: “deploy”, “staging”, “release” — not “it”.
• Include the reason. “We use X because Y” beats “we use X”: six months later the agent can tell when the rule may change.

Naming fact_key

A fact_key is the question a record answers. All records answering the same question should share one key, so that disagreements show up as conflict.

Good	Bad	Why
deploy.staging.method	deploy	Too broad: unrelated deployment facts start to “conflict”.
backend.sessions.storage	redis-decision-2026-10-05	Date and answer in the key: the next version gets a different key and the conflict goes unnoticed.
team.review.migrations	Review Rule	Case and spaces: easy to spell differently.

Rules: lowercase Latin letters, dots between levels “area.subject.property”, no dates, no answer in the key. The exception is period summaries: deploy.weekly-summary.2026-w41.

Sources

When a fact comes from a document, include:

• source_id — a path from the repository root or a URL (docs/deploy.md);
• source_hash — a content hash (sha256sum), always together with source_id;
• source_revision — a commit or version number.

Then you can check freshness with validate_memory later and delete every fact from an outdated document with one forget by source_id. Details: Source and freshness.

Summaries

When a topic has many records, the agent can write a summary. Pass the IDs of the records it was built from in derived_from (up to 50). The summary then inherits the conflict and stale status of its sources and hides nothing unresolved. Details: Conflicts and summaries.

When to forget

• A person confirmed that a fact is wrong.
• A conflict was resolved: the wrong version is deleted by memory_id.
• A document was rewritten: old facts are deleted by source_id before saving new ones.
• A person asked to forget something.

Do not delete records just because they are old: age is not an error. Deletion is soft and affects only records the caller can see.

Confidence

• 0.9–1.0 — read in a document or confirmed by a person;
• 0.5 (default) — the agent’s own conclusion from its work;
• below 0.5 — a hypothesis worth checking.

Retries without duplicates: X-Idempotency-Key

If you write to MMW from your own script or integration over HTTP, add an X-Idempotency-Key header (1–256 printable ASCII characters, no spaces) to remember calls. A retry with the same key and the same input returns the same record instead of creating a second one. The same key with different input fails with 409 Conflict: idempotency key was used with different input. A key applies within one API key, project and workspace.

Note

MCP clients (Claude, Cursor, Codex) generally do not let the model set HTTP headers, so ordinary agent work does not need this. It is for your own integrations and scripts that retry requests after network failures.

An instruction for your agent

Paste this block into CLAUDE.md, AGENTS.md or your Cursor rules and adjust the workspace names.

CLAUDE.md / AGENTS.md

## MMW memory

You have long-term memory in MMW (tools: search, remember, forget, validate_memory).

When to search:
- at the start of a task — on the task's topic, to learn past decisions and agreements;
- before proposing an architecture decision or a deployment method;
- when the user asks "how do we…", "what did we decide…", "why…".
Workspaces: default — project facts, decisions — decisions, docs — facts from documents.

How to read results:
- status=conflict — memory disagrees with itself; do not choose, show both versions to the user;
- status=stale — the source changed; re-read it before acting;
- status=unverified — a normal record; take source_id and confidence into account.

When to remember:
- a decision was made — with its reason (workspace=decisions);
- the root cause of a bug was found and fixed;
- the user stated a rule, agreement or preference;
- a document was read and an important fact follows from it — with source_id, source_hash, source_revision.

How to remember:
- one fact per record, self-contained, using the words people will search for;
- fact_key in the form area.subject.property (deploy.staging.method), no dates, no answer in the key;
- search first: if the fact already exists and has not changed, do not duplicate it;
- summaries get derived_from = IDs of the source records.

Never save: keys, tokens, passwords, connection strings; raw dumps of chats or logs;
temporary state ("a test is running now").

forget only when the user confirmed a fact is wrong, when resolving a conflict,
or when the source document was rewritten (forget by source_id before the new remember calls).

Where next

Core concepts The record fields and statuses the instruction refers to.

Memory Guard What the server scrubs and rejects.

remember reference Every parameter and error.