memory

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.