Skip to main content
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:

​
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: 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: 
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: 
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: 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.