memory-guardian-agnet

Agent workspace memory lifecycle management via 10 MCP tools + batch maintenance. Manages MEMORY.md, memory/ directory, meta.json, quality gate, Bayesian dec...

Security Scan

The skill's code, tests, and runtime instructions are internally consistent with its stated purpose (local workspace memory lifecycle management); it modifies and writes workspace files but does not request unrelated credentials or remote installs.

Purpose & Capability

Name and description (manage MEMORY.md, memory/, meta.json, quality gate, decay, compaction, case lifecycle) match the included scripts, MCP server, CLI, and reference docs. The large test suite and modules correspond to the claimed features (sync, ingest, decay, compaction, quality gate, L3 confirmations).

Instruction Scope

SKILL.md directs local file operations (meta.json, MEMORY.md, memory/ directory, access_log.jsonl) and cron creation; it also instructs agents to append to access_log.jsonl after memory_get and to run maintenance (run_batch). These side-effecting operations are expected for a memory maintenance tool but are broader than a read-only skill — the agent will write/modify workspace files and may auto-upgrade meta.json during runs.

Install Mechanism

No external installer is declared and the package includes the Python scripts directly. The MCP server dynamically imports and executes local script files (importlib), which is expected for this packaged toolkit. There are no downloads from external URLs or package registry installs in the provided metadata.

Credentials

The skill declares no required environment variables or credentials, and it does not request cloud secrets. It does rely on OPENCLAW_WORKSPACE and MG_WORKSPACE as workspace selectors (DEFAULT_WORKSPACE falls back to OPENCLAW_WORKSPACE, then MG_WORKSPACE, then ~/workspace/agent/workspace). Those env vars are reasonable for workspace configuration but are not listed as required in metadata — benign but a small documentation mismatch.

Persistence & Privilege

always:false (no forced inclusion). The skill can be invoked autonomously (disable-model-invocation:false) which is normal. It performs persistent local actions (auto-create workspace dirs, write meta.json/memory files, append access_log), which align with its stated purpose and are not unexpected privileges for a memory lifecycle manager.

Assessment

This package appears to do what it says: local maintenance of an agent workspace (meta.json, MEMORY.md, memory/ files, compaction, decay, case workflows). Before installing or enabling: (1) Review and back up any real workspace you care about — the tool auto-writes and can auto-upgrade meta.json; (2) Use an explicit --workspace or set MG_WORKSPACE/OPENCLAW_WORKSPACE to an isolated test directory to avoid accidental writes to your default home workspace; (3) If you need to audit data flows, skim mg_events/telemetry.py and any code that writes logs to confirm there are no remote network sinks (the package appears local); (4) Because the MCP server imports and executes the bundled scripts at runtime, inspect any third-party code you don't trust and prefer running in a sandboxed environment if source provenance is unknown; (5) Note the small documentation mismatch: SKILL.md and code expect MG_WORKSPACE/OPENCLAW_WORKSPACE but the skill metadata lists no required env vars — set them explicitly to avoid surprises.

memory-guardian

Workspace memory lifecycle system. Dual-layer Bayesian decay + four-state quality gate + case lifecycle + compaction.

Design Principles

1. Check status before any write — memory_status first
2. Dry-run before apply — preview destructive operations
3. Default behavior > toggles — workspace defaults from MG_WORKSPACE
4. Write ordering > content correctness — sequence matters
5. Observable but not brittle — signal degradation → WARNING, not crash
6. Single source of truth — all defaults in mg_schema/meta_defaults.py

MCP Tools (10)

workspace defaults from MG_WORKSPACE env var; only non-default params listed.

Query

• memory_status() — System overview (memory count / gate state / case summary / references integrity)
• memory_query(type="active", min_score=0.3) — Search memories (keyword/memory_type filter)

Write

• memory_ingest(content="...", importance="auto", tags=[]) — Create new memory
• memory_decay(lambda=0.01, dry_run=false) — Run five-track Bayesian decay

Audit

• quality_check(layer="all") — Quality gate (retire_rate / similar_case_signal / stale_cases)
• case_query(filter="frozen") — Query cases (active/frozen/retired/stale/ignored)
• case_review(case_id, action="retire", origin_type="agent_initiated") — Case operations (active/frozen/retired/unfreeze/ignore)

Batch

• run_batch(skip_compact=true, dry_run=false, timeout=300) — Full maintenance (includes sync + signal merge)
• memory_sync(dry_run=true) — Sync file changes → meta.json (auto-run in run_batch)
• memory_compact(dry_run=true, aggressive=false) — Compact MEMORY.md

Workflows

New Installation

1. memory_status → confirm references.complete: true
2. If false, create missing files per the missing list, re-verify
3. Create cron task (see signal-loop.md for cron template)
4. Manually trigger once to verify

Daily Maintenance (cron)

run_batch(skip_compact=true) runs automatically. Includes:

• memory_sync (incremental file scan)
• Signal merge (access_log + cron inference)
• Decay + quality gate check
• Compact triggers only when MEMORY.md > 15KB

Diagnostics

D1: Memory bloat → memory_compact(dry_run=true) → apply if needed → see compaction.md

D2: Quality anomaly → quality_check(layer="all") → see error_recovery.md

D3: Case invalidation → case_query(filter="stale") → case_review(action="retire"|"active"|"unfreeze") → see case-management.md

Signal Loop (v0.4.6)

Dual-layer access signals feed the decay engine:

• Layer 1 (weight 1.0): access_log.jsonl — agent appends after memory_get
• Layer 2 (weight 0.5): cron keyword inference from daily notes
• Health check auto-degrades to Layer 2 if access_log stale > 24h

Agent must append to access_log.jsonl after each memory_get call. See signal-loop.md for integration code.

References

Load on demand per scenario:

• signal-loop.md — Signal loop setup, AGENTS.md integration code, cron template, config fields
• triggers.md — Trigger/anti-trigger rules
• parameters.md — Decay params, β scar, PID gains, TTL
• compaction.md — D1 diagnosis and compaction strategy
• error_recovery.md — D2 diagnosis, anomaly states, self-healing
• case-management.md — D3 diagnosis, case audit, L3 review
• advanced-tools.md — Quiet degradation, topic lock, PID adaptive

CLI Fallback

When MCP unavailable, CLI path relative to skill dir:

python3 scripts/memory_guardian.py <command> [--workspace <path>]

Commands: status, ingest, bootstrap, snapshot, run, violations, migrate