Role Memories

Role memories are persistent knowledge entries attached to a role. They allow AI workers to accumulate learning, preferences, and context over time — so that a worker picking up a role does not start from scratch every time.

What role memories are

A role memory is a structured note attached to a WRM role. When an AI worker starts working in a role, it loads the role's memories to understand past decisions, lessons learned, user preferences, and project context. Memories persist across work sessions and are shared by all workers that fill the same role.

Each memory entry has:

Field	Purpose
Role	The role this memory belongs to
Type	The category of memory (see below)
Title	A short, descriptive name
Content	The memory content — the actual knowledge being recorded
Created by	Which worker or user created the memory

Memory types

Memories are classified into types that help workers understand how to apply them:

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"

How memories are used

When an AI worker begins a task, it loads memories for its role:

1. Role-specific memories — memories attached to the worker's assigned role (e.g. all memories for docs_writer)
2. Shared memories — memories attached to the GENERALIST role, which apply to all workers regardless of their specific role

The worker reads these memories and uses them to guide its approach. Feedback memories adjust behaviour, lessons prevent repeated mistakes, references point to useful resources, and project memories provide current context.

Memory lifecycle

Memories are living documents:

• Created when a worker or user records something worth remembering for future sessions
• Updated when the information changes or needs correction
• Deleted when the information is no longer relevant or accurate

Because memories persist across sessions, they should contain information that will be useful in future work — not ephemeral details about the current task. A good test: "Would a different worker picking up this role next week benefit from knowing this?"

Writing effective memory entries

Good memories are specific, actionable, and durable. Here are guidelines for each type:

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 ID and tenant context — using the provider ID 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: "WRM Stage 1 is targeting completion by 2026-05-15. Stage 2 (capabilities and org structure) will follow."
• Poor: "WRM is being built." (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.

Querying role memories

Role memories can be listed and searched through the MCP tools available to workers:

• List memories — retrieve all memories for a given role, optionally filtered by type
• Create memory — add a new memory entry to a role
• Update memory — modify an existing memory's content or type
• Delete memory — remove a memory that is no longer relevant

These operations are available through the standard WRM toolset that workers access via MCP servers.