Memory Guardian

Memory health monitoring, integrity checks, and 3-layer memory architecture for AI agents. Use when agents need to prevent memory loss, detect context overfl...

Security Scan

The code is a straightforward read-only memory health scanner, but the human-facing instructions request sensitive operations (extracting/aggregating credentials into permanent memory) and reference environment state not declared by the skill—those mismatches are concerning.

Purpose & Capability

The script implements file-scanning, size/staleness/duplicate detection, and index checks under a workspace path—this aligns with a 'memory health' tool. However, the SKILL.md claims broader behaviors (automatic promotions, migrations to FAISS/Neo4j, and an explicit protocol to 'extract: Credentials/keys → permanent') that are not implemented in the code. Asking the agent to extract and centralize credentials is not necessary for a read-only checker and is disproportionate to the stated purpose.

Instruction Scope

Runtime instructions instruct running the provided scanner (fine) but also instruct policy-level actions such as promoting secrets/credentials into permanent storage and deleting session files. Those instructions broaden scope to sensitive data handling. The scanner itself only reads files and prints a report; the SKILL.md gives the agent authority to perform destructive/promotional actions that would affect secrets and long-term storage, which is scope creep and risky.

Install Mechanism

No install spec is provided (instruction-only with a bundled script). No downloads or installers—low installation risk.

Credentials

The code reads OPENCLAW_WORKSPACE (defaulting to ~/.openclaw/workspace) but the skill declares no required environment variables. There's a mismatch between declared requirements and actual behavior. More importantly, the SKILL.md explicitly instructs extracting/storing credentials into permanent memory yet requests no credentials itself—this is an unexplained handling of sensitive data.

Persistence & Privilege

The skill is not set to always:true and does not autonomously modify other skills. The provided script, as written, is read-only: it scans and prints a report. However, the human instructions reference deleting session files and promoting contents, which would be destructive if implemented. At present the code does not implement --fix/auto-repair behavior despite the documentation, which is an implementation mismatch to watch for.

What to consider before installing

This skill bundles a benign-looking file-scanner but its markdown instructions instruct the agent to extract and permanently store credentials and to perform promotions/deletions—behavior not implemented in the shipped script. If you want to use it: (1) Do not run it against a workspace that contains real secrets until you audit and sandbox it. (2) Confirm with the author whether automatic promotion/deletion or credential extraction is implemented; prefer a read-only mode. (3) If you must run it, set OPENCLAW_WORKSPACE to a safe test directory and back up your memory directory first. (4) Ask the publisher to explicitly declare required env vars and to remove any instructions that aggregate credentials into permanent storage or to implement strict safeguards for secrets handling.

Prevent memory loss and context overflow. 3-layer architecture with automated health checks.

Architecture

Layer 1: Working Memory (session files, 7-day retention)
    ↓ promote durable facts before deletion
Layer 2: Permanent Memory (never pruned, manual only)
    ↓ migrate to vector store at 5,000+ lines
Layer 3: Archive (batch docs, value stacks — disk forever)

Health Checks

Run python3 scripts/memory_check.py on heartbeat or manually. Catches:

• Files over 300 lines (split needed)
• Total memory over 3,000 lines (yellow alert → prune)
• Stale session files (>7 days → promote + delete)
• Duplicate content across files
• MEMORY.md index inconsistency
• Orphan files not referenced anywhere

Danger Zones

Total Lines	Risk	Action
< 2,000	🟢 Green	Normal operations
2,000-3,000	🟡 Yellow	Prune sessions, compress old entries
3,000-5,000	🟠 Orange	Aggressive promotion to permanent, archive sessions
5,000+	🔴 Red	Semantic search returns noise → migrate to FAISS

Promotion Protocol

Before deleting ANY session file, extract:

1. Credentials/keys → permanent (NEVER lose these)
2. Architecture decisions → permanent/business-strategy.md
3. Infrastructure changes → permanent/outreach-infrastructure.md
4. New project summaries → permanent/projects/[name].md
5. User preferences → permanent/user-system.md

Everything else (debug logs, intermediate results) → delete.

Migration Triggers

Trigger	Action
permanent/ > 5,000 lines	Migrate to FAISS vector store
Batch value-stack > 100 items	Add embeddings for semantic retrieval
ChatGPT corpus loaded	FAISS mandatory
Cross-batch connections > 50	Consider Neo4j knowledge graph

Emergency Recovery

Everything is git-tracked. If memory corrupts:

1. git log memory/ → find last good state
2. git checkout <hash> -- memory/ → restore
3. Rebuild MEMORY.md index from ls memory/permanent/

Context Budget

Component	Tokens	Notes
System prompt	~2,000	Fixed
MEMORY.md	~1,500	Keep lean
Active session	~1,000	Today only
memory_search	~500	On-demand
Total overhead	~5,000	Of 200K+ available