v6.0.0 — Capacity Management + Integrity Protection

What's New

• MEMORY.md capacity management — 5000 char soft cap with usage% tracking, warns at 80%, blocks writes at 100%
• USER.md auto-update — --user "preference" writes to USER.md with 1500 char cap
• Auto-snapshot before compaction/GC — stored in memory/snapshots/, keeps last 10
• Integrity monitoring — cron detects accidental MEMORY.md wipe (<100 bytes) and auto-restores from latest snapshot
• Periodic snapshots every 6h via cron
• --consolidate command — analyze and deduplicate MEMORY.md entries with snapshot safety
• --snapshot command — manual MEMORY.md snapshot
• Boot shows capacity% (📊 MEMORY XX%)
• Health check includes capacity info for both MEMORY.md and USER.md + snapshot count
• Gap alerting in cron (>2 consecutive days missing)

Install

clawhub install memory-engine-3layer
# or
git clone https://github.com/ZackO2o/memory-engine.git

Inspired by Hermes Agent bounded memory design + OpenClaw Dreaming separation.

Full changelog: CHANGELOG.md

v3.0.0 — Complete Feedback Implementation

All 6 items from memory-engine-feedback-v2.9.md implemented:

New Scripts:

• memory-resume.js — Zero-latency session recovery (<2000 tokens)
• memory-auto-extract.js — Mine session transcripts for events (OpenClaw format)

New Features:

• search --last N [--today] [--tag T] — Time-ordered recent entries without FTS5
• maintain --gc [--apply] — MEMORY.md stale entry detection & cleanup
• Write dedup — Skip entries similar to last 5
• Session size warning in boot.js + cron.sh (4MB/8MB thresholds)
• Flush prompt fix — Removed NO_REPLY escape, forces at least one write
• Cron: auto-extract from reset sessions + session size monitoring

v2.9.0: Token Optimization — Smart Truncation

Token Consumption Report

Operation	Current	After 6 months
boot.js (full)	~854 tokens	~5900 ❌
boot.js (default, max-chars=1500)	~520	~372 ✅
search --max 3	~251	~251
write --today	~21	~21
Typical session (boot + 5 writes + 3 searches)	~1176	~1176 ✅
vs. reading all daily files	~7928	~50000+

Optimizations

• Smart MEMORY.md truncation: When MEMORY.md exceeds --max-chars (default 1500), outputs all section headers + most recent entries per section. Saves 94% tokens at 18KB file size.
• Keyword-context search: Truncates around the matching keyword instead of from the start — shows the most relevant snippet.
• Controls: --max-chars N on boot.js and search.js; --full for no truncation

Key Insight

Memory search costs ~251 tokens for 3 results.
Reading all daily files costs ~7928 tokens (and growing).
That's 97% savings today, 99.5% savings at 6 months.

v2.8.0: Backup & Disaster Recovery

New Features

• memory-backup.sh: Auto-backup workspace to GitHub private repo. Runs every 6h via cron (integrated into memory-cron.sh Step 6). Only pushes if changes exist. Backs up: MEMORY.md, daily logs, SOUL.md, USER.md, AGENTS.md, openclaw.json, crontab.
• memory-restore.sh: One-command disaster recovery after OpenClaw reinstall. Clones backup, restores openclaw.json, restores crontab, rebuilds search index. Interactive safety prompt if workspace already exists.

Setup

# One-time: init git in workspace and push
cd ~/.openclaw/workspace
git init && git branch -M main
git remote add origin https://<token>@github.com/<user>/openclaw-workspace.git
bash skills/memory-engine/scripts/memory-backup.sh

Restore

bash memory-restore.sh https://<token>@github.com/<user>/openclaw-workspace.git

v2.7.0: Unified timezone — auto-reads from openclaw.json

Critical Fix

• Date mismatch between scripts and OpenClaw memory-flush: OpenClaw uses agents.defaults.userTimezone to compute dates, but our scripts used TZ env var (often unset → UTC in cron environments). This caused cross-day mismatches:
  • Example: At UTC 02:00, OpenClaw (NY timezone) writes memory/2026-04-09.md, but scripts (UTC) would write memory/2026-04-10.md
  • Health check would falsely report "No log for today"
  • All fixed: scripts now auto-read userTimezone from openclaw.json

New

• _timezone.js shared module: All 6 scripts use the same timezone source
• Resolution order: OPENCLAW_TZ env > openclaw.json > TZ env > /etc/timezone > /etc/localtime symlink > UTC
• memory-cron.sh also reads from openclaw.json

Verified

• UTC, America/New_York, Asia/Shanghai, Asia/Tokyo, Europe/London, Australia/Sydney
• Cross-day boundary scenarios
• Cron environment (no TZ set)
• Date matches OpenClaw's formatDateStampInTimezone() output exactly

v2.6.0: Auto-recovery + date search fix + production hardening

Fixes

• Auto-recovery from corrupted database: search.js, index.js, and boot.js now detect SQLITE_NOTADB/SQLITE_CORRUPT and auto-rebuild the index instead of crashing with an unhandled exception.
• Date-only search: Queries like "4月2日" now correctly return all content from April 2nd. Previously returned empty results because date tokens (月/日) were searched as literal text in chunks.
• Date scope: Date-only queries no longer include undated files (MEMORY.md).

Improvements

• memory-boot.js retries with --force rebuild if initial index update fails
• SKILL.md documents boot.js in Commands section

Verified

• Full clean-install simulation (empty workspace → all features working)
• Corrupted DB recovery tested (search/index/boot all recover)
• 31 test scenarios passed including: empty workspace, concurrent writes, large files, special characters, SQL injection, date filtering, CJK/English/mixed search

v2.5.0: OpenClaw deep integration — flush fix + boot command + index sync

Critical Fix

• memory-flush prompt: Removed instructions to write MEMORY.md (OpenClaw marks it read-only during flush) and run exec commands (restricted during flush). Previous prompt would fail silently, wasting tokens every compaction cycle.

New Features

• memory-boot.js: Single-command session startup — runs health check, updates index, outputs MEMORY.md content. Saves 2 tool calls per session.
• postIndexSync: "async": OpenClaw auto-syncs memory search index after compaction.
• Cron stale detection: Compares file hashes against index, auto-rebuilds when out of sync (catches memory-flush writes that bypass autoReindex).

Based on OpenClaw Source Analysis

• Studied thread-bindings-SYAnWHuW.js (memory-flush, compaction-safeguard, heartbeat logic)
• Confirmed: flush tool writes restricted to memory/YYYY-MM-DD.md via wrapToolMemoryFlushAppendOnlyWrite
• Confirmed: MEMORY.md, SOUL.md, AGENTS.md marked read-only via MEMORY_FLUSH_READ_ONLY_HINT
• Confirmed: postIndexSync triggers runPostCompactionSessionMemorySync after compaction

v2.4.0: Score merging fix + orphan cleanup + temporal decay tuning

Critical Fixes

• Score merging: FTS5 and LIKE fallback scores now merged via max() — previously FTS5 would "claim" a chunk with a low BM25 score, preventing the LIKE path from scoring it higher. This caused precision issues like "Entry 499" ranking below random unrelated chunks.
• Orphan cleanup: memory-index.js now detects and removes entries for files deleted from disk. Previously, stale records accumulated and could pollute search results.

Improvements

• Temporal decay: Half-life increased from 30 → 90 days. Old memories retain meaningful weight (90d = 50% vs previous 12.5%).
• Search precision: Verified with stress test (500 entries) — exact match now consistently ranks #1.

v2.3.0: Unified search — FTS5 + LIKE fallback

Critical Fix

• Substring matching: Previously FTS5 missed alphanumeric tokens like XYZ789, mixed CJK-English queries, and any substring that wasn't a full FTS5 token. Now all queries go through both FTS5 (fast, when applicable) AND LIKE fallback (catches everything FTS5 misses).

Improvements

• Unified search logic — removed 3 separate code paths (CJK/English/date-filtered) into one
• Case-insensitive LIKE matching for all languages
• Consistent TF-density scoring across all search modes
• Timezone-aware date comparison in compact.js

v2.2.1: Bug fixes — heartbeat schema + timezone + compact safety

Fixed

• heartbeat config: enabled+intervalMinutes → every: "30m" (matches OpenClaw schema, eliminates "Unrecognized keys" warning)
• Timezone-aware dates: All scripts now respect TZ env variable (previously used UTC, causing wrong dates after 8pm in non-UTC timezones)
• Compact safety: Skips already-compacted files, won't overwrite archived originals on re-run
• Cron timezone: memory-cron.sh inherits system TZ from /etc/timezone