---
name: memory
description: Two-layer memory system with Reflection-managed knowledge files.
always: true
---

# Memory

## Structure

- `SOUL.md` — Bot personality and communication style. **Managed by Reflection.** Avoid editing unless the task is explicitly about identity/persona.
- `USER.md` — User profile and preferences. Managed by Reflection and inline learning.
- `memory/MEMORY.md` — Long-term facts (project context, important events). Managed by Reflection and inline learning.
- `memory/BUGS.md` — Confirmed bugs, limitations, and durable workarounds. Updated only via inline learning (not touched by Reflection).
- `memory/history.jsonl` — append-only JSONL, not loaded into context. Prefer the built-in `grep` tool to search it.

## Search Past Events

`memory/history.jsonl` is JSONL format — each line is a JSON object with `cursor`, `timestamp`, `content`.

- For broad searches, start with `grep(..., path="memory", glob="*.jsonl", output_mode="count")` or the default `files_with_matches` mode before expanding to full content
- Use `output_mode="content"` plus `context_before` / `context_after` when you need the exact matching lines
- Use `fixed_strings=true` for literal timestamps or JSON fragments
- Use `head_limit` / `offset` to page through long histories
- Use `exec` only as a last-resort fallback when the built-in search cannot express what you need

Examples (replace `keyword`):

- `grep(pattern="keyword", path="memory/history.jsonl", case_insensitive=true)`
- `grep(pattern="2026-04-02 10:00", path="memory/history.jsonl", fixed_strings=true)`
- `grep(pattern="keyword", path="memory", glob="*.jsonl", output_mode="count", case_insensitive=true)`
- `grep(pattern="oauth|token", path="memory", glob="*.jsonl", output_mode="content", case_insensitive=true)`

## Important

- Use surgical edits only for durable facts, preferences, and confirmed bugs.
- Do NOT edit `memory/history.jsonl` directly.
- If you notice outdated information, it will be corrected when Reflection runs next.
- Users can view Reflection's activity with the `/reflection-log` command.
