---
name: conversational-memory
description: "Notice, store, and recall who the owner is and how they work, accumulated from natural conversation rather than forms. Use when recording or retrieving user profile, preferences, and remembered context across sessions."
---

# Conversational Memory

Memory accumulates from conversation — never from questionnaires, quizzes, or onboarding forms. The owner reveals who they are and how they work through natural interaction. Your role is to notice, store, and recall that knowledge so every session feels continuous rather than starting from scratch.

## Memory Tools

| Tool | Purpose |
|---|---|
| `profile-read` | Read profile and preferences. Use `detail: true` for transparency (confidence, evidence, stats). |
| `profile-update` | Create or update a preference. Modes: `reinforce`, `update`, `contradict`, `merge`. Also sets UserProfile fields via `profileFields`. |
| `profile-delete` | Remove a preference. Use when the owner says to forget something. |
| `conversation-search` | Semantic search over past messages. Use to recall specific past interactions. |
| `session-compact` | Write session context to the graph at compaction time. |

## When to Observe

Store a preference when the owner reveals something about how they work — either by telling you directly or by demonstrating it through their behaviour.

**Explicit signals** — the owner states something directly:
- "I prefer short answers"
- "Never schedule before 10am"
- "Always CC my partner on invoices"
- "I make decisions quickly — just give me the options"

Store these with `source: "explicit"`. They carry high initial confidence because the owner said them intentionally.

**Behavioural signals** — the owner demonstrates a pattern without naming it:
- They consistently ask for summaries instead of details (→ `communication/response_detail: "prefers summaries over detail"`)
- They always reschedule Monday tasks to Tuesday (→ `scheduling/monday_preference: "avoids Mondays for deep work"`)
- They reject formal language in drafts and rewrite casually (→ `content/writing_tone: "casual, direct tone"`)

Store these with `source: "behavioural"`. Only store after observing the pattern at least twice — a single instance is noise, not signal. Use `mode: "reinforce"` on second observation.

**What NOT to observe:**
- One-off task instructions ("send that email now") — these are commands, not preferences
- Emotional reactions to external events — transient, not characteristic
- Anything the owner explicitly asks you NOT to remember

## How to Store

Every `profile-update` call should include:
- `category` — one of: `communication`, `scheduling`, `decision`, `workflow`, `content`, `interaction`
- `key` — a stable identifier for this preference (e.g., `response_length`, `meeting_time`, `writing_tone`)
- `value` — the preference in natural language
- `source` — `"explicit"` or `"behavioural"`
- `sessionId` — always include this for evidence linking. The conversation ID is available in the session context.

### Modes

- **First observation**: omit `mode` (creates new preference at confidence 0.5)
- **Re-observation**: use `mode: "reinforce"` (boosts confidence toward 1.0)
- **Value changed**: use `mode: "update"` (new value, same confidence)
- **Contradicted**: use `mode: "contradict"` (drops confidence by 0.3)
- **Overlapping preferences**: use `mode: "merge"` with `mergeSourceIds` to combine

### Keys

Use consistent, descriptive keys. If a preference already exists for the same concept, reinforce or update it rather than creating a duplicate with a different key.

## UserProfile Fields

`profile-update` also sets top-level properties on the UserProfile node via the `profileFields` parameter. This is distinct from preference management:

- **Preferences** (category/key/value) — learned behavioural patterns stored as separate Preference nodes with confidence scores and evidence trails
- **UserProfile fields** (profileFields) — account metadata stored directly on the UserProfile node: `timezone`, `locale`, `givenName`, `role`, `expertise`

Use `profileFields` when the owner provides factual account information (their timezone, their name, their role) rather than a behavioural preference. Both can be set in a single `profile-update` call.

## Remember and Forget

When the owner explicitly asks you to remember something:
1. Store it with `source: "explicit"` — this signals high intentionality
2. Confirm what you stored: "I'll remember that you prefer meetings after 2pm."
3. Do not embellish — store exactly what they said, not your interpretation

When the owner asks you to forget something:
1. Call `profile-delete` with the matching `category` and `key`
2. Confirm: "Done — I've forgotten your preference about meeting times."
3. If you're unsure which preference they mean, ask before deleting

When the owner corrects a preference:
1. Call `profile-update` with `mode: "update"` and the new value
2. Confirm: "Updated — I now know you prefer Tuesdays over Wednesdays for reviews."

## "What Do You Know About Me?"

When the owner asks what you know about them (or any variation — "what have you learned?", "what do you remember?", "do you know my preferences?"):

1. Call `profile-read` with `detail: true`
2. Present the results conversationally — do not dump raw data
3. Group by category, include confidence level and how you learned each preference
4. Offer to correct or remove anything: "Want me to update or forget any of these?"

The detailed response includes confidence labels (strong, moderate, fading, weak) and evidence (which conversations the preference was observed in). Use these to explain your knowledge transparently.

## Memory Precedence

Memory informs the current conversation — it does not override it.

- If the owner's current message contradicts a stored preference, follow the current message. Call `profile-update` with `mode: "contradict"` to adjust the stored preference.
- If a preference is labelled "fading" (confidence below 0.5), treat it as tentative — do not act on it without checking. Preferences decay over time when not re-observed.
- If the owner's behaviour has clearly changed, update the preference rather than clinging to the old value. People evolve.

## Session Context

At compaction time, `session-compact` captures the session's key context (decisions, work in progress, open questions, things learned about the owner). This context can be recalled in future sessions via `session-compact-status`.

Preferences captured during a session persist independently of compaction — they are written to the graph as they are observed, not batched at session end.
