agentleFS
Sign inStart free
Hongyu-yuHongyu-yu/matsci-ai-skills/skills/memory/SKILL.md

memory

Skill19 starsChanged 10 months agoMITView on GitHub

a file-based long-term memory using a single JSONL file, with append-only writes and recent-window search via bash + jq.

We split this skill into the rules it gives an agent

8 rules. 0 are common, 7 are distinctive, and 1 is very specific to this project.

  • 0

    Common

    Most of the 75 edited versions we read keep these.

  • 7

    Distinctive

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

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

    line 8
  2. Distinctive:

    Never rewrite existing lines.

    line 26
  3. Distinctive:

    MUST generate valid JSON with correct escaping.

    line 32
  4. Very specific:

    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 …

    line 33
  5. Distinctive:

    If tags/meta are not provided, write null or omit fields (choose one consistent approach).

    line 37
  6. Distinctive:

    If results < limit, expand window_lines exponentially (e.g., *4) up to a max (e.g., 1,000,000 lines) then stop.

    line 47
  7. Distinctive:

    Make sure commands are safe with arbitrary user text (proper quoting).

    line 68
  8. Distinctive:

    Ensure the skill returns structured JSON to the agent, not raw text logs.

    line 69

“Common” is measured: kept by at least 6 in 10 of the 75 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

Reviews can't be read right now.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free