OpenClaw Memory v4

Lightweight file-based memory system for single-user AI agents. No databases, no APIs — just markdown files with tiered loading, grep tagging, and automatic...

Security Scan

The skill is internally consistent with its stated purpose — a local, file-based memory system — but has a few implementation details you should review (hardcoded paths, file-write behavior, and an ambiguous 'commit' step) before installing.

Purpose & Capability

Name/description (file-based, tiered memory) matches what the skill asks to do: read and write markdown files, run small shell scripts for archive/health/atomic writes, and use grep/head for tag discovery. There are no network endpoints, external APIs, or unrelated credentials requested.

Instruction Scope

SKILL.md instructs the agent to write to and read from a local memory directory and to run provided scripts (archive, atomic write, health-check). This is expected for a file-based memory system, but the runtime will create/modify files on disk (working-buffer, episodic, semantic, etc.). The weekly-review mentions 'commits all changes' without providing the commit mechanism — unclear whether it runs git or another VCS; that should be clarified before allowing autonomous runs.

Install Mechanism

Instruction-only skill with no install spec and only three small local scripts — low install risk. Nothing is downloaded or executed from remote URLs.

Credentials

No environment variables, credentials, or external services are requested (proportional). One caveat: the scripts hard-code MEMORY_DIR=/home/irtual/.openclaw/workspace/memory. That path is a local filesystem location and not a secret, but the hardcoded path may not match the user's environment and could cause unexpected behavior if edited or replaced by the agent at runtime.

Persistence & Privilege

Does not request always:true and does not attempt to modify other skills or system-wide settings. The skill's normal operation writes files into a workspace directory (expected for a memory system). The agent's ability to autonomously invoke the skill is the platform default and not flagged here.

Assessment

This skill appears to do what it says: manage a local, file-based memory folder and run small maintenance scripts. Before installing or allowing autonomous invocation: (1) Inspect and, if needed, update the hardcoded MEMORY_DIR in the scripts to point to a safe folder you control (don’t leave it pointing to an unexpected home path). (2) Confirm what 'commits all changes' means — if it will run git commit/push, make sure you understand where it will push and with which credentials. (3) Be aware the skill will write files (working-buffer, episodic, semantic, etc.) — avoid pointing it at directories containing secrets you don’t want written or mutated. (4) Run the scripts in a sandbox or on a copy of your workspace first to verify behavior (archive, atomic-write, health-check). If you want higher assurance, ask the maintainer for an explicit parameter to set MEMORY_DIR (or patch the scripts) and for a clear description of any VCS commands used during weekly review.

File-based 3-tier memory for single-user AI agents. ~12KB, 9 files, zero dependencies.

Core Design

3 types, 4 tiers, 10 mechanisms that fit in a terminal.

3 Types

Type	What	Lives
Episodic	What happened	memory/episodic/YYYY-MM-DD.md
Semantic	What I know	memory/semantic/*.md
Procedural	How to do things	memory/procedural/*.md

4 Tiers

Tier	Files	When to load
HOT	MEMORY.md (≤60 lines)	Every session
WARM	semantic/*.md, procedural/*.md	By context (grep tags)
COLD	episodic/, archive/	On query
BUFFER	working-buffer.md	During active task

Directory Structure

MEMORY.md                          ← HOT, ≤60 lines, always loaded
├── memory/
│   ├── episodic/                  ← COLD, one per day
│   │   └── YYYY-MM-DD.md          ← events, decisions, signals
│   ├── semantic/                  ← WARM, one per domain
│   │   ├── infrastructure.md      ← IP, ports, services
│   │   ├── preferences.md         ← style, rules, habits
│   │   ├── projects.md            ← active projects
│   │   └── decisions.md           ← final decisions with why
│   ├── procedural/                ← WARM, how-to + lessons
│   │   ├── lessons-learned.md     ← post-mortems, anti-patterns
│   │   └── (other how-to files)
│   ├── working-buffer.md          ← BUFFER, active task scratchpad
│   ├── archive/YYYY/MM/           ← episodic >30 days, auto-moved
│   └── scripts/
│       ├── archive-old-episodic.sh ← TTL archiver
│       ├── atomic-write.sh         ← crash-safe file writes
│       └── health-check.sh         ← invariant validation

10 Mechanisms

1. WAL-lite — Files Before Responses

Before answering with important info (decisions, corrections, facts), write to working-buffer.md first. Then reply. Files survive restarts.

2. Compaction Recovery

After session compaction or reset:

1. Read MEMORY.md
2. Read episodic for today + yesterday
3. Read working-buffer.md (if stale, check for pending work)
4. Resume from file contents

3. Canonical Owner Rule — Principle, Not Mechanism

Each class of fact has exactly one home. Never duplicate:

Fact type	Lives in
IP, ports, services	semantic/infrastructure.md
Preferences, style, rules	semantic/preferences.md
Commands, how-to	procedural/*.md
Events, decisions, timeline	episodic/YYYY-MM-DD.md
Post-mortems, anti-patterns	procedural/lessons-learned.md
Final decisions with rationale	semantic/decisions.md

4. Atomic Writes

Prevent corrupted files on crash. Use dd with fsync:

# Via script:
echo "content" | bash scripts/atomic-write.sh /path/to/file.md

# Manual: tmp → fsync → mv
TMP=$(mktemp /path/to/file.md.tmp.XXXX)
dd if="$TMP" of=/path/to/file.md conv=fsync status=none && rm -f "$TMP"
# Or simpler:
cp --force "$TMP" /path/to/file.md && sync
mv is atomic on same filesystem — just ensure file is complete first.

5. Closure Blocks in Episodic

End every episodic note with 4 lines:

Updated: YYYY-MM-DD
Decisions: what was changed
Signal: what I learned about the system
Open: remaining items (or "none")

Decision = what I changed. Signal = what I learned.

6. Episodic TTL

Archive files older than N days into archive/YYYY/MM/:

bash scripts/archive-old-episodic.sh 30   # default 30

7. Buffer Rotation

When working-buffer.md exceeds 80 lines:

1. Append to daily episodic file
2. Clear the buffer
3. Continue

Rotation is soft — if in the middle of a complex task, defer until session end.

8. Weekly Review (cron, Monday 9:00)

Automated review that:

1. Reads episodic files from past 7 days
2. Extracts decisions → semantic/decisions.md
3. Extracts lessons → procedural/lessons-learned.md
4. Runs health-check.sh — fix any FAILs
5. Runs episodic archival (>30 days)
6. Updates MEMORY.md freshness + open questions
7. Clears stale working-buffer
8. Commits all changes

If nothing meaningful changed → skip with "No meaningful changes".

9. Health Check (invariant validation)

Before important operations, run:

bash scripts/health-check.sh

9 checks: tags on line 2, frozen vocabulary, last_verified <30d, buffer <80 lines, open questions ≤5, closure blocks, Active Decisions link integrity, episodic file count, WAL integrity (no orphaned buffer entries). Returns exit code 0 if all pass, 1 if any fail.

10. Grep-Based Tag Discovery

Every WARM file has #tags: on line 2:

grep -rl "qdrant" memory/                         # all files mentioning qdrant
grep -rl "#tags:.*networking" memory/              # files tagged networking
head -2 memory/**/*.md | grep "#tags:"             # discover all tags

Emergency Procedures

If health-check.sh FAIL:

1. Do not answer complex questions requiring memory-based decisions
2. Tell user: "Memory integrity check failed"
3. Fix any FAIL checks before proceeding

Tag Vocabulary (Frozen)

infrastructure: tailscale, tailnet, docker, synapse, matrix, coturn, qdrant, ubuntu, systemd, ufw, fail2ban, samba, ssh, networking, gateway, pm2 preferences: rules, style, workflow, memory, habits projects: audit, skills, security, review procedural: deepseek, puppeteer, benchmark, troubleshooting, tasks, checklist, backup, diagnostics lessons: postmortem, errors, fixes, anti-patterns

Do not invent new tags.

Friction Log

If a task takes >5 minutes of waiting/googling → note it inline with #friction: tag in the working buffer. Weekly review moves recurring friction → lessons-learned.md.

Safety Rules

• trash > rm — never delete, always move
• Atomic writes for all file modifications
• No duplicate facts across files (Canonical Owner)
• No credentials in episodic notes
• Commit changes after updates
• Weekly review validates last_verified dates

Why This Works

• Text > brain: Files survive restarts. Mental notes don't.
• Grep > database: No vector DB, no API, no dependency chain.
• Small context: 60-line MEMORY.md fits in any prompt.
• Self-maintaining: TTL archival + weekly review + health check + buffer rotation.
• Hard to break: Atomic writes, canonical owners, frozen tags, invariant checks.

See references/design-rationale.md for the full decision trail from the 4-round AI consultation that shaped this system.