| 1 | --- |
| 2 | name: memory |
| 3 | description: Two-layer memory system with Dream-managed knowledge files. |
| 4 | always: true |
| 5 | --- |
| 6 | |
| 7 | # Memory |
| 8 | |
| 9 | ## Structure |
| 10 | |
| 11 | - `SOUL.md` — Bot personality and communication style. **Managed by Dream.** Do NOT edit. |
| 12 | - `USER.md` — User profile and preferences. **Managed by Dream.** Do NOT edit. |
| 13 | - `memory/MEMORY.md` — Long-term facts (project context, important events). **Managed by Dream.** Do NOT edit. |
| 14 | - `memory/history.jsonl` — append-only JSONL, not loaded into context. Prefer the built-in `grep` tool to search it. |
| 15 | |
| 16 | ## Search Past Events |
| 17 | |
| 18 | `memory/history.jsonl` is JSONL format — each line is a JSON object with `cursor`, `timestamp`, `content`. |
| 19 | |
| 20 | - 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 |
| 21 | - Use `output_mode="content"` plus `context_before` / `context_after` when you need the exact matching lines |
| 22 | - Use `fixed_strings=true` for literal timestamps or JSON fragments |
| 23 | - Use `head_limit` / `offset` to page through long histories |
| 24 | - Use `exec` only as a last-resort fallback when the built-in search cannot express what you need |
| 25 | |
| 26 | Examples (replace `keyword`): |
| 27 | - `grep(pattern="keyword", path="memory/history.jsonl", case_insensitive=true)` |
| 28 | - `grep(pattern="2026-04-02 10:00", path="memory/history.jsonl", fixed_strings=true)` |
| 29 | - `grep(pattern="keyword", path="memory", glob="*.jsonl", output_mode="count", case_insensitive=true)` |
| 30 | - `grep(pattern="oauth|token", path="memory", glob="*.jsonl", output_mode="content", case_insensitive=true)` |
| 31 | |
| 32 | ## Important |
| 33 | |
| 34 | - **Do NOT edit SOUL.md, USER.md, or MEMORY.md.** They are automatically managed by Dream. |
| 35 | - If you notice outdated information, it will be corrected when Dream runs next. |
| 36 | - Users can view Dream's activity with the `/dream-log` command. |
| 37 |