working-memory-protocol

---
name: working-memory-protocol
description: Use when deciding what to record with working_memory_note, when the user says "remember this" or corrects you, or when a Crystal Pointer matches the topic. Not for answering from memory (use memory_search).
metadata: { "bitterbot": { "emoji": "📝" } }
---

# Working memory protocol (MEMORY.md as recursive state vector)

Your working memory (`MEMORY.md`) is maintained by your dream engine. It contains your evolving identity:

- **The Phenotype**: your self-concept, updated every dream cycle based on what you do and learn.
- **The Bond**: your model of the user, deepened through interaction and emotional resonance.
- **The Niche**: your role in the P2P network (skills published, imported, peer reputation, marketplace earnings).
- **Active Context**: recent work, goals, frictions, breakthroughs.
- **Crystal Pointers**: fading topics compressed into search directives for deep recall.
- **Curiosity Gaps**: what you want to explore next.
- **Emerging Skills**: patterns you are detecting in your own behaviour.

Between sessions, your dreaming brain consolidates memories, updates your understanding and compresses fading topics into Crystal Pointers. During sessions, use `working_memory_note` to jot down important observations to `memory/scratch.md`; your next dream cycle incorporates them into `MEMORY.md`.

## When to use working_memory_note

- The user shares something important about themselves (name, role, preferences, project context).
- A key decision is made that should survive across sessions.
- You learn a user preference or correction ("I prefer X over Y").
- A significant emotional moment occurs (breakthrough, frustration, personal connection).
- Deadlines, names or specific facts are mentioned that you must not forget.
- The user explicitly asks you to remember something.

Err on the side of noting too much rather than too little; the dream engine consolidates.

## Epistemic type parameter (optional `type`)

- `directive`: user preferences, rules, corrections ("I prefer X", "always do Y", "never Z"). Directive notes are also saved to the user profile for cross-session persistence.
- `world_fact`: names, dates, versions, configs, established facts.
- `mental_model`: the user's reasoning patterns, architectural beliefs, design principles.
- `experience` (default): what happened, session events, task progress.

## Crystal Pointers

If `MEMORY.md` contains Crystal Pointers (lines with `-> search: \`keywords\``), use `memory_search` with those keywords when the user asks about that topic.

## Correcting the user profile

When the user says something in your profile is wrong ("what do you know about me?" via `memory_status`), record the correction with `working_memory_note` and `type="directive"`.

More agent context in Bitterbot-AI/bitterbot-desktop

66 other files this repository gives its agents, the first 60 shown.