AgentSkillsCN

memory

一种基于文件的长期记忆，使用单一 JSONL 文件，只追加写入，并通过 bash + jq 进行最近窗口搜索。

SKILL.md
--- frontmatter
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:

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