Memory Skill

Overview

• •Provide two functions: memory_write and memory_search.
• •Store memory in a single append-only JSONL file (one JSON object per line).
• •Search a recent tail window first; only expand the window if needed.

Workflow decision tree

Recall context

Run memory_search at the start of every task unless the user explicitly says not to.

Persist knowledge

Run memory_write only when the user explicitly asks to store memory, and only for stable, reusable information.

Avoid writing

Do not write secrets, tokens, one-off details, or transient reasoning.

Setup

Source the script before using the functions:

source scripts/memory.sh

Optionally override the storage file:

export MEMORY_FILE="$HOME/.codex/memory.jsonl"

Storage format

• •Store entries in ${MEMORY_FILE:-~/.codex/memory.jsonl}; create it if missing.
• •Write one JSON object per line with at least:
  • •ts: ISO8601 timestamp
  • •type: string (e.g., note, fact, task, todo)
  • •content: string (raw text)
  • •tags: optional array of strings
  • •meta: optional object
• •Never rewrite existing lines; append only.

Write workflow (memory_write)

• •Pass input as JSON: {type, content, tags?, meta?}.
• •Generate valid JSON via jq; do not hand-build JSON strings.
• •Append exactly one JSON object per line.

Example:

memory_write '{"type":"note","content":"Prefers terse status updates.","tags":["preference"]}'

Search workflow (memory_search)

memory_search(query)

• •Pass input as JSON: {q, limit?, window_lines?}.
• •Treat q as a literal substring.
• •Search a tail window first; expand exponentially if results are insufficient.
• •Return output: {results, truncated, used_window_lines}.

Example:

memory_search '{"q":"prefers","limit":5,"window_lines":20000}'

Requirements

• •Depend on standard unix tools: bash, touch, tail, rg (ripgrep), jq.
• •Provide fallbacks: if rg missing, use grep; if jq missing, fail with a clear error.
• •Make sure commands are safe with arbitrary user text (proper quoting).
• •Ensure the skill returns structured JSON to the agent, not raw text logs.
• •Require bash and jq; use rg or grep, tail, date, printf, and touch.
• •Allow tools: Bash(date:) Bash(jq:) Bash(printf:) Bash(touch:) Bash(tail:) Bash(rg:) Bash(grep:*)