Memory

Memory 模块：一步一步教程

用于为项目建立轻量索引并执行文本检索，帮助日常诊断和上下文定位。

步骤 1：查看当前 memory 状态

mosaic --project-state memory status

预期：即使未索引过，也会有可读状态输出。

步骤 2：执行首次索引

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

步骤 3：检索索引内容

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

步骤 4：按目录+命名空间重建索引

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

大仓库建议结合命名空间和增量索引，提高迭代速度并优化索引生命周期管理。

步骤 5：需要时清理索引

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

步骤 6：查看并清理命名空间

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` 现已支持按命名空间文档数量配额清理，并在 JSON 输出中给出清理原因分类。

步骤 7：JSON 自动化检查

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

步骤 8：持久化清理策略并执行

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

步骤 9：通过 cron 事件自动执行策略

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`（或 `memory.cleanup`）会读取持久化 policy 限制，并支持 `dry_run`/`force` 布尔参数。