Memories

Memories are persistent knowledge entries that WRM workers accumulate and read back. They let a worker draw on past decisions, lessons, and context each time it picks up a task.

Every memory is scoped — it belongs to the whole organisation, a domain, a role, a repository, or a single worker — and memories written at a shared scope pass through a curation lifecycle before they become binding on other workers.

What a memory contains

Field	Purpose
Scope	Which layer the memory applies to (see below)
Anchor	The specific role, domain, worker, or repository the scope points at
Type	The category of memory — feedback, lesson, reference, or project
Title	A short, descriptive name
Content	The memory content — the actual knowledge being recorded
Status	Where the memory sits in the curation lifecycle
Created by	Which worker or user recorded the memory

Memory scopes

Every memory has exactly one scope, and each scope is tied to exactly one anchor. An organisation memory has no anchor at all; a role memory names a role and nothing else.

Scope	Anchor	Applies to	Example
ORG	None	Every worker, in every role and domain — binding org-wide policy	"All user-facing copy uses British English spelling"
DOMAIN	A domain	Any worker assigned to that domain, whatever its role	"Billing rounds to four decimal places before currency conversion"
ROLE	A role	Every worker filling that role, in any domain	"Code reviewers check for missing tenant scoping before anything else"
REPO	A repository	Workers with that repository in their current context	"The docs site build fails on broken relative links — check before pushing"
WORKER	A single worker	That worker only — its private working notes	"Retry the flaky integration suite once before reporting a failure"

Scope keeps a lesson learned in one part of the platform with the work it applies to. For example, a repository-specific quirk stays with that repository, while a genuine organisation-wide policy is visible everywhere.

Memory types

Every scope uses the same set of types. The type tells a worker how to apply what it reads.

Type	Purpose	Example
FEEDBACK	Corrections or confirmations from users about how work should be done	"Always use British English spelling in documentation for this project"
LESSON	Insights learned from past work — things that went wrong or patterns that worked well	"The billing API returns 429 errors after 100 req/min — add retry logic"
REFERENCE	Pointers to where information can be found in external systems	"Architecture decisions are tracked in the ADR folder at docs/adr/"
PROJECT	Ongoing project context — who is working on what, deadlines, and constraints	"Merge freeze starts 2026-05-01 for the v3.0 release cut"

The curation lifecycle

Anything a worker writes at a shared scope is a proposal, not a fact. Memories move through four statuses:

Status	Meaning
PROPOSED	Written but not yet accepted — not returned to other workers
ACTIVE	Accepted and in circulation
REJECTED	Reviewed and declined; retained as a record of the decision
SUPERSEDED	Replaced by a newer memory, which is recorded as the replacement

Where a new memory starts depends on its scope:

• Worker-scoped memories are active immediately. A worker's private notes apply to that worker alone, so they take effect as soon as they are written.
• Organisation, domain, role, and repository memories start as proposed. They become visible to other workers once promoted, and the promotion records which worker promoted them and when.

Review at the shared scopes is what keeps them trustworthy. A memory becomes policy for other workers only after someone has agreed that it should.

Duplicate suppression

Workers rediscover the same lesson repeatedly. When a new memory is written, it is compared against existing active memories. A near-identical match reinforces the memory already held — that memory records having been encountered again, and the store keeps a single entry for the point.

Repetition therefore strengthens a memory, and each distinct lesson is represented once.

How memories are retrieved

A worker retrieves the memories that apply to it. When it starts a task, its context — which worker it is, which role it holds, which domain it is working in, and which repositories are involved — is resolved first, and memories are matched against that context.

Retrieval is semantic: the task description is compared against the meaning of stored memories rather than matched on keywords. For example, a memory about "rate limiting on the billing endpoint" is returned for a task described as "the invoice sync keeps failing under load".

Results come back layered by scope, in this order:

1. Organisation — always included
2. Domain — only if the memory's domain matches the worker's current domain
3. Role — only if the memory's role matches the worker's role
4. Repository — only if the memory's repository is in the worker's current context
5. Worker — only the calling worker's own memories

Within each layer, the closest semantic matches come first. Retrieval returns active memories only.

note

Semantic retrieval depends on each memory having been indexed. Memories written through the standard tooling are indexed as they are created; a bulk indexing operation is available to backfill any that were imported or seeded without an index.

Which repositories count as "in context" for a worker comes from its domain's repository list, and whether a given repository contributes memories is configurable per repository. See Domains and Repositories for how that context is assembled.

Writing effective memories

Good memories are specific, actionable, and durable. Two questions decide most cases:

1. Is this worth remembering? "Would a different worker picking this up next week benefit from knowing this?" Record what will still be useful then; leave out detail that belongs only to the current task.
2. What is the narrowest scope that still covers it? For example, a quirk of one repository belongs at repository scope. Choosing a scope wider than the memory warrants puts it in front of every worker the wider scope covers, which is the most common mistake.

Feedback memories

Record what the user wants and why:

• Good: "Use active voice in all user-facing documentation. Why: the style guide requires it and the technical writer flagged passive constructions in the last review."
• Poor: "Write better docs." (too vague to act on)

Lesson memories

Record what happened and what to do differently:

• Good: "Provider lookups require both the provider identifier and tenant context — using the provider identifier alone can return unexpected results across tenants. Learned when a query returned duplicates."
• Poor: "Be careful with queries." (no specific guidance)

Reference memories

Record where to find information, not the information itself:

• Good: "API rate limits for each provider are documented in the provider's merchant configuration notes field."
• Poor: "Anthropic rate limit is 1000 req/min." (will go stale; point to the source instead)

Project memories

Record time-sensitive context with dates:

• Good: "The billing domain migration is targeting completion by 2026-05-15. The reporting cutover follows."
• Poor: "Billing is being rebuilt." (no actionable context)

tip

When deciding whether to create a memory, ask: "Is this something I learned that is not obvious from reading the code or documentation?" If the answer is yes, it is probably worth recording.

Working with memories

Memories are managed through the WRM toolset available to workers:

• Search memories — semantic search across every scope that applies to the calling worker's context
• List memories — retrieve memories filtered by scope, anchor, type, or status
• Create memory — record a new memory; shared scopes start as proposed
• Update memory — revise content, or transition status to promote, reject, or supersede an entry
• Bulk index — backfill semantic indexing across memories awaiting it

Related documentation

• Domains and Repositories — how domain and repository context is defined
• Knowledge Sources — retrieving from documentation and code, as distinct from accumulated memories
• Worker Management Overview — how memories fit alongside the other WRM concepts