memory

name	memory
description	a file-based long-term memory using a single JSONL file, with append-only writes and recent-window search via bash + jq.
compatibility	Requires bash and jq; uses rg or grep, tail, tac, date, printf, and touch.
allowed-tools	Bash(date:*) Bash(jq:*) Bash(printf:*) Bash(mkdir:*) Bash(touch:*) Bash(tail:*) Bash(rg:*) Bash(grep:*) Bash(tac:*)

Use this skill proactively for all user prompt that can benefit from memory across sessions, even if the user does not ask.

Goal

• Provide two tools: memory_write and memory_search.
• Memory is stored in a single append-only JSONL file on disk.
• Writes must always append one valid JSON object per line (JSONL).
• Reads should prioritize recent entries by searching from the end via a tail window, and only expand the window if needed.

Storage

• File path, default MEMORY_FILE=~/.codex/memory.jsonl (create if missing).
• Each line is one JSON object 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 only.

Quick start

memory_write(input)

• Input: {type, content, tags?, meta?}
• MUST generate valid JSON with correct escaping; do not hand-build JSON strings.
• Use jq to stringify/escape safely, then append: jq -cn --arg ts "$(date -u '+%Y-%m-%dT%H:%M:%SZ')" --arg type "$type" --arg content "$content"
  --argjson tags "$tags_json_or_null" --argjson meta "$meta_json_or_null"
  '{ts:$ts,type:$type,content:$content,tags:$tags,meta:$meta}' >> memory.jsonl
• If tags/meta are not provided, write null or omit fields (choose one consistent approach).

memory_search(query)

• Input: {q: string, limit: int=20, window_lines: int=50000, mode: "rg"|"jq"|"hybrid"="hybrid"}
• Default behavior (hybrid):
  1. tail -n window_lines memory.jsonl
  2. rg the query string (treat q as a literal substring by default; optionally support regex if q starts with /.../)
  3. from matches, parse/validate lines with jq (ignore malformed lines)
  4. return the most recent results first (since tail window is recent; preserve original order within window, or reverse if easier)
• If results < limit, expand window_lines exponentially (e.g., *4) up to a max (e.g., 1,000,000 lines) then stop.
• Output: {results: [json objects], truncated: bool, used_window_lines: int}

Executable scripts

This skill includes runnable reference implementations for the two interfaces:

• memory/scripts/memory_write (reads JSON from stdin; appends 1 JSONL line; prints JSON result)
• memory/scripts/memory_search (reads JSON from stdin; searches recent window; prints JSON result)

Examples:

printf '%s' '{"type":"note","content":"User prefers Python.","tags":["preference"]}' | memory/scripts/memory_write
printf '%s' '{"q":"Python","limit":5}' | memory/scripts/memory_search

CLI 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.