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