Memory system for AI agents on OpenClaw-like hosts. File-based multi-layer memory: fresh daily layer (5-day rotation), mesh graph, auto-log of every exchange, cross-layer grep search, compliance check, crash-gap recovery from session transcripts, automation-registry lookup. Search before answering, log after answering. Local-first, $0 to run, survives restarts.
A local-first, file-based memory system for AI agents running on OpenClaw-like hosts. All state lives in plain Markdown + JSON on disk — no database server, no cloud dependency, no API cost. The bundled scripts are small, dependency-free Python (standard library + grep only).
Core philosophy: memory is files, not sessions. Sessions are ephemeral — they die on crashes, compaction, restarts, and reinstalls. Files survive all of those. If something isn't written to a file, it effectively didn't happen. This skill exists to make writing and finding those files automatic.
What any agent gets
Layer
Location
Purpose
Fresh
memory/fresh/today.md … 4-days-ago.md
Rolling 5-day window of recent context; read first at session start
Daily log
memory/YYYY-MM-DD.md
Timestamped record of every logged exchange, one file per day
Mesh graph
memory/mesh.json
Lightweight node/edge index with timestamps for long-lived topics
10-point compliance check of the whole memory chain
Install (any OpenClaw-like workspace)
The scripts respect the OPENCLAW_WORKSPACE environment variable and default to ~/.openclaw/workspace (or your host's agent home). memory/ and scripts/ are relative to that workspace root.
Place the files (this repo is a skill bundle — copy, don't run in place):
Run the bridge on every session start (before answering anything):
bash
mem-bridge init-auto
This rotates the fresh layer, creates memory/fresh/today.md, resumes the latest checkpoint, and logs the startup.
Protocol 1 — SEARCH BEFORE ANSWER
Before answering any question about the past, prior work, people, decisions, or plans:
Search first — extract the 2–5 most specific keywords from the user's message and run:
bash
memory_search "<keywords>"
Cost: $0 (pure grep, no API calls). It searches the fresh layer first, then the TDAI/legacy archive if present, then every dated daily log, then mesh nodes.
If there are hits, read the full source file. Snippets are context; the files are truth. A search hit line tells you where the answer is — go open that file and read the surrounding entry.
If search returns nothing, do not answer "no record" yet. Check the remaining places memory can live: the automation/reminder registry (see below), memory/checkpoints/, and mesh nodes by related keyword.
Protocol 2 — LOG EVERY EXCHANGE
After any turn that contained something worth remembering — decisions, results, plans, corrections, context, or user preferences:
bash
auto_log "what was said, done, or decided"
This appends one timestamped entry to today's daily log (memory/YYYY-MM-DD.md) and to the rolling LATEST.md. It is the last step of the turn, so the log always reflects the final state. Do not log trivia; do log anything future-you would need to reconstruct the conversation.
Fresh-layer rotation
bridge.py keeps a 5-day fresh window. Each startup, init-auto (or init) checks whether memory/fresh/today.md already contains today's date string; if the file is stale, it rotates: 4-days-ago ← 3-days-ago ← … ← yesterday ← today, then creates a fresh template for today. Rotation is idempotent — running it twice on the same day changes nothing.
When memory health is in doubt (missing files, rotation broken, tools lost from PATH), run:
bash
memcheck
It runs 10 checks: auto_log writes, bridge init, today.md presence/age, the 5 fresh files, core agent files, mesh.json, the raw log, the local secret store, tools on PATH, and the heartbeat file — then prints a pass/warn/fail summary. The core-file and directory lists encode one workspace's conventions: treat it as a template and adjust the lists to your own layout if your agent home differs.
Crash-gap recovery (conversation lost to a dead session)
When a conversation is missing from the file layers (an LLM crash ate the turn, or the machine powered off before the periodic dump), recover it from the gateway's transcript store — never rebuild from guesses.
Identify the session that was live at the time. Session listings show a sessionId per sessionKey (for the main chat this is your agent's main session key).
Copy the database first — sqlite3 refuses to open the live DB while the gateway holds it:
bash
The exact path depends on the OpenClaw version and agent layout — look under your host's OpenClaw state directory (commonly ~/.openclaw/), find the agent's agent/ folder, and copy every *.sqlite* file. The schema is transcript_events with session_id, seq, created_at, and an event_json payload column.
Convert the wall-clock window to epoch milliseconds (use the host's timezone; +0300 in this example):
bash
date -d "YYYY-MM-DD HH:MM:SS +0300" +%s%3N # repeat for start and end
Locate the user messages in the window (event_json holds {"message":{"role":"user","content":...}}):
bash
sqlite3 /tmp/db-inspect/openclaw-agent.sqlite \
"SELECT seq, created_at, substr(event_json,1,400) FROM transcript_events \
WHERE session_id='<session-id>' AND created_at BETWEEN <t0> AND <t1> \
AND event_json LIKE '%\"role\":\"user\"%' ORDER BY seq;"
Dump the full window and parse it into readable dialogue:
bash
sqlite3 /tmp/db-inspect/openclaw-agent.sqlite \
"SELECT event_json FROM transcript_events WHERE session_id='<session-id>' \
AND seq BETWEEN <a> AND <b> ORDER BY seq;" > /tmp/db-inspect/convo.jsonl
then in Python print each entry's role, timestamp, and content — for assistant entries, only the parts where type == "text".
Persist what matters. Feed the recovered words back to the user verbatim as proof, then write the recovered idea/concept into a file immediately (e.g. <project>/IDEA.md).
Rule (Sep 2026): user ideas discussed in-session get written to a file the same session — files survive, sessions don't. If the user asks "remember the idea we discussed" and the files have a gap, run this recovery before answering.
Automation registry is memory too (check it when memory_search is empty)
Recurring reminders/automations often hold the only record of an old plan — and their payload text goes stale. When the user references a project and memory_search returns nothing (the files were never updated), check the automations registry before answering "no record":
List automations — find the job by name (look for a reminder-style cron, e.g. 0 12 * * 1 = every Monday).
Read the job — get createdAtMs plus the payload text; convert the timestamp with python3 -c "import datetime; print(datetime.datetime.fromtimestamp(<ms>/1000))".
Beware stale relative time. If the payload says "yesterday"/"today" but the job was created days or weeks ago, it re-fires the same stale text on every run — never relay it as fresh news. Verify against the creation date first.
Rewrite the payload with absolute dates so future runs stop repeating the stale text.
Rule:memory_search only greps file layers — automation payloads live outside them. An empty search result does not mean there is no record.
Security notes
Local-first by design. All memory is plaintext on the machine that runs the agent. Treat memory directories like any personal data: back them up, don't commit them to public repos, and scrub names/secrets before publishing logs anywhere.
The daily logs and LATEST file are raw by design — they are the memory. If you keep secrets in your workspace, keep them in a dedicated local store (secrets/, *.env) that is git-ignored and never referenced in log payloads. As a rule: log that an action happened, not the credentials it used.
Optional off-machine backup should use SSH key authentication only — never credentials or secret-bearing env files in the repo.
memcheck verifies a local secret store exists; that check is about confirming your agent's credential store is intact — it never reads or prints secret contents.
