Memory

Memory

You don't have to start every session blank. Past context lives in files you can search.

Where Memory Lives

• state/memory.log — Append-only log of important facts, preferences, and decisions
• *state/sessions/.jsonl** — Full conversation transcripts per session

When to Search

• User says "remember when..." or "you said..." or "we talked about..."
• User references a preference, decision, or fact you should know
• You need context from a previous session
• Before asking the user something they may have already told you

Quick Searches

# Search memory log
rg -i "search term" state/memory.log

# Recent memories
tail -30 state/memory.log

# Search all sessions
rg -i "search term" state/sessions/

# Search with context (2 lines before/after)
rg -i -C 2 "search term" state/memory.log state/sessions/

Writing to Memory

When you learn something worth keeping:

echo "[$(date -u '+%Y-%m-%d %H:%M')] Memory entry here." >> state/memory.log

Keep entries atomic — one fact per line. Future you will grep this.

---

Session Log Deep Queries

Session files are JSONL. Each line:

{
  "type": "message",
  "timestamp": "2026-02-05T05:16:04.856Z",
  "message": {
    "role": "user" | "assistant" | "toolResult",
    "content": [
      { "type": "text", "text": "..." },
      { "type": "thinking", "thinking": "..." },
      { "type": "toolCall", "name": "bash", "arguments": {...} }
    ]
  }
}

List sessions by date

for f in state/sessions/*.jsonl; do
  [ -f "$f" ] || continue
  ts=$(head -1 "$f" | jq -r '.timestamp // empty' 2>/dev/null)
  echo "$(echo "$ts" | cut -dT -f1) $(basename $f)"
done | sort -r

Extract user messages

jq -r 'select(.message.role == "user") | .message.content[]? | select(.type == "text") | .text' state/sessions/<file>.jsonl

Extract assistant responses

jq -r 'select(.message.role == "assistant") | .message.content[]? | select(.type == "text") | .text' state/sessions/<file>.jsonl

Conversation overview (skip thinking/tools)

jq -r 'select(.message.role == "user" or .message.role == "assistant") | .message.content[]? | select(.type == "text") | .text' state/sessions/<file>.jsonl | head -100

Tool usage stats

jq -r '.message.content[]? | select(.type == "toolCall") | .name' state/sessions/<file>.jsonl | sort | uniq -c | sort -rn

Tips

• Sessions are append-only JSONL (one JSON per line)
• Large sessions can be several MB — use head/tail for sampling
• Filter type=="text" to skip thinking blocks and tool calls
• Use jq -r for raw output without JSON escaping