> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clawkitchen.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Memory System

> This document explains the ClawRecipes memory system in practical terms, especially as it appears in the team editor.

If you want the short version:

* memory is **file-first**
* not all memory is the same
* private continuity, team coordination, team knowledge, and role memory should stay separate
* the team editor should help you see and manage the right layer without mixing them up

This doc builds on the canonical memory model doc:

* [MEMORY\_MODEL.md](memory-model)

***

## Why this exists

Without a clear memory system, teams end up dumping everything everywhere:

* private context leaks into shared files
* ticket status gets mixed with durable knowledge
* role-specific learnings get lost
* nobody knows where to put anything

ClawRecipes avoids that by being explicit about memory layers.

***

## The four memory layers

ClawRecipes uses four memory layers:

1. assistant continuity memory
2. team coordination docs
3. team knowledge memory
4. role memory

The canonical explanation lives here:

* [MEMORY\_MODEL.md](memory-model)

This page is the easier operational guide.

***

## Layer 1: assistant continuity memory

What it is:

* the assistant’s own continuity
* preferences
* personal working context
* long-running private context

Typical files:

* `SOUL.md`
* `USER.md`
* `memory/YYYY-MM-DD.md`
* `MEMORY.md`

Important rule:

* this does **not** belong in the team workspace

Use this for:

* assistant continuity
* private context
* user-specific preferences

Do not use it for:

* shared team knowledge
* team ticket history
* shared operational docs

***

## Layer 2: team coordination docs

What it is:

* the team’s operating surface
* plans, tickets, status, assignments, checklists

Typical files:

* `work/backlog/`
* `work/in-progress/`
* `work/testing/`
* `work/done/`
* `notes/plan.md`
* `notes/status.md`
* `TICKETS.md`
* `AGENTS.md`

Use this for:

* what the team is doing right now
* blockers
* decisions attached to tickets
* ongoing work coordination

Do not use it for:

* curated long-term knowledge base entries
* private assistant memory

***

## Layer 3: team knowledge memory

What it is:

* shared durable knowledge for the whole team
* facts worth keeping
* canonical links
* runbooks
* known fixes
* decisions worth reusing later

Typical files:

```text theme={null}
shared-context/memory/
  team.jsonl
  pinned.jsonl
```

Use this for:

* reusable knowledge
* facts the whole team should remember
* high-signal decisions worth pinning

This is the memory layer most closely associated with a memory tab in the team editor.

***

## Layer 4: role memory

What it is:

* continuity for one role inside the team
* role-specific learnings and playbooks

Typical files:

```text theme={null}
roles/<role>/
  MEMORY.md
  memory/YYYY-MM-DD.md
```

Use this for:

* role-specific learnings
* role runbooks
* role continuity that should not become global team knowledge yet

Examples:

* QA-specific release checks
* dev-specific implementation gotchas
* lead-specific prioritization habits

***

## Team editor angle

From the team editor point of view, the memory system should feel like a set of clearly separated panels, not one giant dumping ground.

A good team editor should help you understand:

* what belongs in team memory vs role memory
* what is operational status vs durable knowledge
* what is pinned vs append-only
* what should stay private and never move into team memory

### The most useful things the team editor can surface

#### Memory overview

* short explanation of the memory layers
* link to the canonical memory model doc

#### Team memory

* `shared-context/memory/team.jsonl`
* `shared-context/memory/pinned.jsonl`
* counts / recent entries / pinned items

#### Coordination docs

* `notes/status.md`
* `notes/plan.md`
* current ticket lanes

#### Role memory

* links into `roles/<role>/MEMORY.md`
* links into role daily memory files

#### Policy docs

* `notes/memory-policy.md`
* any team-specific memory conventions

In other words:

* the editor should help you navigate the memory system
* the files remain the real source of truth

***

## What goes where?

### Put it in team coordination docs when...

* it is about current work
* it is ticket-specific
* it is a progress update
* it is a blocker or immediate plan

### Put it in team knowledge memory when...

* it is reusable later
* the whole team should know it
* it is a known fix / canonical answer / stable reference

### Put it in role memory when...

* it mainly belongs to one role
* it is useful continuity for that role
* it is not yet broad enough to become team-wide knowledge

### Keep it in assistant continuity memory when...

* it is private context
* it is user/assistant specific
* it should not leak into the team workspace

***

## Pinned vs append-only memory

### Append-only memory

This is the stream of memory as things are learned.

Examples:

* `team.jsonl`
* daily memory files
* status logs

### Pinned memory

This is the smaller curated set of high-signal items worth keeping easy to find.

Example:

* `pinned.jsonl`

Rule of thumb:

* append everything useful first
* pin only the things you expect to matter again later

***

## Suggested habits

### After finishing work

* update the ticket comments
* append to `notes/status.md`
* save artifacts to `shared-context/agent-outputs/`
* if a reusable lesson emerged, write it to team memory
* if it is especially important, pin it

### During triage or lead review

* move short-lived work chatter into tickets/status docs
* move durable lessons into team knowledge memory
* curate pinned memory so it stays high-signal

### For role agents

* keep role-specific continuity in role memory
* escalate broadly useful knowledge into team memory

***

## Common mistakes

### 1) Treating status logs like a knowledge base

`notes/status.md` is for operational history, not your long-term memory system.

### 2) Dumping private context into shared memory

Private assistant continuity should stay private.

### 3) Pinning too much

If everything is pinned, nothing is pinned.

### 4) Never promoting useful knowledge

If good lessons stay buried in tickets forever, the team never really learns.

### 5) Skipping role memory

Role memory is useful because not every lesson belongs at the whole-team level.

***

## Simple example

Imagine a team learns these three things:

1. “Ticket 0042 is blocked waiting on API credentials.”
2. “The fix for workflow-runner approval retries is to clear stale locks before requeue.”
3. “QA should always capture screenshots for UI changes.”

Where should they go?

* \#1 → ticket comments / `notes/status.md`
* \#2 → team knowledge memory (`team.jsonl`, maybe pin it)
* \#3 → role memory for QA, and maybe team memory too if it is now a team-wide rule

***

## How this connects to the canonical doc

This page is the practical operating guide.

The canonical model and boundaries remain here:

* [MEMORY\_MODEL.md](memory-model)

If you want the philosophy and the exact layer definitions, read that doc.
If you want to know how to use the memory system day-to-day, start here.