# Best practices

> What an agent should and should not remember, how to name fact_key, work with sources and summaries — plus a ready instruction for CLAUDE.md or AGENTS.md.

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](/memory/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](/agent/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](/memory/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](/memory/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.

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.

```markdown title="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