Memory

Memory Module: Step-by-Step Tutorial

Use this module to index project content and run lightweight text retrieval for operational context.

Step 1: Check current memory status

mosaic --project-state memory status

Expected: status output exists even before first index.

Step 2: Build first index

mosaic --project-state memory index \
  --path . \
  --max-files 500 \
  --max-file-size 262144 \
  --max-content-bytes 16384

Expected: index completes without read/permission failures.

Step 3: Search indexed content

mosaic --project-state memory search "gateway retry" --limit 20
mosaic --project-state memory search "agents route" --limit 10

Expected: relevant snippets are returned for your query terms.

Step 4: Re-index with tighter scope and namespace

mosaic --project-state memory index \
  --path cli \
  --namespace ops \
  --max-files 300 \
  --incremental \
  --stale-after-hours 24 \
  --retain-missing
mosaic --project-state memory status --namespace ops

Use namespace + incremental runs for faster iteration and safer memory lifecycle control.

Step 5: Clear memory cache when needed

mosaic --project-state memory clear
mosaic --project-state memory status

Use clear after major repo reshaping or test resets.

Step 6: Review and prune namespaces

mosaic --project-state memory status --all-namespaces
mosaic --project-state memory prune --max-namespaces 5 --dry-run
mosaic --project-state memory prune --max-documents-per-namespace 1000 --dry-run
mosaic --project-state memory prune --max-namespaces 5 --max-age-hours 168

`memory prune` now supports size quota cleanup per namespace and returns reason breakdown in JSON output.

Step 7: CI-friendly JSON checks

mosaic --project-state --json memory status --namespace ops
mosaic --project-state --json memory search "security" --namespace ops --limit 5

Step 8: Persist cleanup policy and run it

mosaic --project-state memory policy get
mosaic --project-state memory policy set --enabled true --max-documents-per-namespace 1000 --min-interval-minutes 60
mosaic --project-state memory policy apply
mosaic --project-state --json memory policy apply --dry-run --force

Step 9: Run policy automatically via cron event

mosaic --project-state --json cron add \
  --name memory-cleanup \
  --event mosaic.memory.cleanup \
  --every 3600 \
  --data '{"dry_run":false}'
mosaic --project-state --yes --json cron tick
mosaic --project-state --json cron run <job-id> --data '{"force":true}'

`mosaic.memory.cleanup` (or `memory.cleanup`) uses persisted policy limits and supports payload booleans `dry_run` and `force`.