# memory-guardian **Repository Path**: zcf_fengqing/memory-guardian ## Basic Information - **Project Name**: memory-guardian - **Description**: No description available - **Primary Language**: Python - **License**: MulanPSL-2.0 - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 2 - **Forks**: 0 - **Created**: 2026-03-31 - **Last Updated**: 2026-04-02 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # memory-guardian `memory-guardian` 是一个面向 Agent 工作区的本地记忆维护工具集，围绕 `meta.json`、快照、质量门控、衰减、判例迁移和数据流观测提供统一 CLI。当前版本主入口为 [`scripts/memory_guardian.py`](scripts/memory_guardian.py)，在不切换默认存储后端的前提下，已经把 schema、repo、telemetry、state 和 ingest service 分层收口到 `scripts/` 目录下。 ## 适用场景 - 维护基于 `memory/meta.json` 的长期记忆或判例库 - 将历史 `mem_*` 记录迁移为更稳定的 `case_*` 数据 - 对写入质量、异常状态、L3 人工确认和失效 case 做治理 - 为 Agent 会话提供可重复执行的 dry-run / apply 运维流程 - 追踪各模块 hit / miss、输入输出量和数据管道断裂候选 ## 当前能力 - 统一 CLI 入口：状态检查、写入、bootstrap、快照、维护流程 - Schema 归一化：`mg_schema.normalize_meta()` 负责历史字段兼容和默认值补齐 - Repo / App 分层：`mg_repo` 与 `mg_app` 收口 `meta.json` 持久化和 ingest 编排 - Telemetry：`mg_events.telemetry` 记录模块命中、输入输出量和报表 - 质量门控：支持 `NORMAL / WARNING / CRITICAL / RECOVERING` 状态演进 - L3 人工确认：支持待确认、确认、拒绝、超时降级 - PID 自适应：按 scene group 调整阈值 - Case 无效化：低置信度连续触发后冻结，并进入人工 review 队列 - 快照与审计：`run` 会联动 `snapshot`，用于跨时间对比工作区变化 ## 项目结构 ```text memory-guardian/ ├─ scripts/ │ ├─ memory_guardian.py # 统一 CLI 入口 │ ├─ mg_utils.py # 通用工具：meta 读写、时间、分词、保护规则 │ ├─ mg_schema/ # schema 归一化与默认值 │ ├─ mg_repo/ # meta.json 持久化抽象 │ ├─ mg_app/ # ingest service │ ├─ mg_events/ # telemetry / dataflow 统计 │ ├─ mg_state/ # quality gate 状态与规则 │ ├─ quality_gate.py # 质量门控模块 │ ├─ l3_confirm.py # L3 人工确认 │ ├─ pid_adaptive.py # PID 自适应控制 │ ├─ case_invalidate.py # case 无效化与 review 队列 │ └─ ... # decay / compact / diff / migrate 等脚本 ├─ tests/ # unittest 回归套件 ├─ docs/ # 设计文档、RFC、实现计划 ├─ CHANGELOG.md ├─ AGENTS.md └─ SKILL.md ``` ## 工作区约定 工具默认依赖工作区中的以下结构： ```text / ├─ MEMORY.md ├─ memory/ │ ├─ meta.json │ └─ YYYY-MM-DD.md └─ .memory-guardian/ └─ diff-snapshots/ ``` - 通过环境变量 `OPENCLAW_WORKSPACE` 指定默认工作区 - 也可以在每个命令后显式传入 `--workspace ` - 建议在自动化环境中始终显式指定 `--workspace`，避免误写到默认目录 ## 快速开始 ### 1. 查看当前状态 ```bash python scripts/memory_guardian.py status --workspace ``` 这会输出： - `meta.json` 版本与记忆总量 - 不同 `status` 的数量分布 - `memory_compact.py`、`memory_dedup.py`、`memory_decay.py --dry-run` 的联动结果 ### 2. 预览一次完整维护 ```bash python scripts/memory_guardian.py run --dry-run --workspace ``` 推荐先执行 dry-run，再决定是否执行： ```bash python scripts/memory_guardian.py run --apply --workspace ``` ### 3. 写入一条记忆 ```bash python scripts/memory_guardian.py ingest \ --content "记录一条新经验" \ --importance 0.7 \ --tags "project,decision" \ --workspace ``` 也支持 case 字段模式： ```bash python scripts/memory_guardian.py ingest \ --situation "当用户要求直接改文档" \ --judgment "先补 README 和操作说明" \ --consequence "降低后续接手成本" \ --action-conclusion "先整理命令，再补工作流" \ --workspace ``` ## 常用命令 ### 主入口 `memory_guardian.py` ```bash python scripts/memory_guardian.py status --workspace python scripts/memory_guardian.py run --dry-run --workspace python scripts/memory_guardian.py run --apply --workspace python scripts/memory_guardian.py ingest --content "..." --importance 0.7 --tags "project" --workspace python scripts/memory_guardian.py bootstrap --workspace python scripts/memory_guardian.py snapshot --workspace python scripts/memory_guardian.py migrate --dry-run --workspace python scripts/memory_guardian.py migrate --dry-run --no-backup --workspace python scripts/memory_guardian.py migrate-bootstrap --dry-run --workspace python scripts/memory_guardian.py migrate-042 --dry-run --workspace python scripts/memory_guardian.py violations-health --workspace python scripts/memory_guardian.py security --sec-command risk --workspace python scripts/memory_guardian.py quality-gate --qg-command status --workspace python scripts/memory_guardian.py l3-confirm --l3-command pending --workspace python scripts/memory_guardian.py pid-adaptive --pid-command status --workspace python scripts/memory_guardian.py case-grow --grow-command record-trigger --grow-id --workspace python scripts/memory_guardian.py case-invalidate --inv-command review --workspace ``` ### 独立模块 ```bash python scripts/dataflow_report.py --workspace python scripts/quality_gate.py status --workspace python scripts/l3_confirm.py pending --workspace python scripts/pid_adaptive.py history --workspace python scripts/case_invalidate.py check --dry-run --workspace ``` ## 典型运维流程 ### 日常巡检 1. 运行 `status` 2. 运行 `run --dry-run` 3. 查看 `dataflow_report.py` 4. 如存在待处理项，再检查 `quality-gate`、`l3-confirm`、`case-invalidate` ### 首次接入旧工作区 1. 备份工作区 2. 执行 `bootstrap` 3. 执行 `migrate --dry-run`，如不想生成备份可显式传 `--no-backup` 4. 执行 `migrate-bootstrap --dry-run` 5. 执行 `status` 与 `run --dry-run` ### schema / 版本升级 1. 先运行 `migrate-042 --dry-run` 2. 确认输出无异常后再执行 `--apply`，不要与 `--dry-run` 同时使用 3. 升级后重新跑 `status`、`run --dry-run`、`dataflow_report.py` ## 统一 CLI 补充说明 - `violations-health` 用于直接查看违规规则健康度汇总，不需要再手动切到子脚本。 - `security --sec-command risk` 在不传 `--action` 时，会列出全部已知 action 的风险分级；传 `--action ` 时才做单项评估。 - `case-grow --grow-command record-trigger` 需要配合 `--grow-id ` 使用。 - `migrate --no-backup` 会显式关闭 v0.3 -> v0.4 迁移备份；`migrate-042` 的 `--apply` 与 `--dry-run` 互斥。 ## 测试与验证 仓库当前以 `unittest` 为主，核心命令： ```bash python -m unittest discover -s tests -p "test_*.py" -v python tests/test_all.py python scripts/memory_guardian.py status --workspace python scripts/memory_guardian.py run --dry-run --workspace python scripts/dataflow_report.py --workspace ``` 当前已拆分的回归覆盖包括： - bootstrap 判例迁移 - 高重要性保护 - schema 归一化 - telemetry / dataflow 报表 - compaction / 日志轮转 - ingest service - typed decay - quality gate 状态 - snapshot / 审计事件 - CLI 行为 ## 设计取向 - 保留 `scripts/` 作为兼容入口，不做一次性大重写 - 优先修数据流，再做模块抽象 - `meta.json` 仍是默认事实源 - 所有危险操作前优先使用 dry-run - 通过 telemetry 验证模块是否真正吃到数据，而不只看代码路径存在 ## 注意事项 - 不要提交真实敏感记忆数据、密钥或令牌 - 执行 `--apply` 前确认 `OPENCLAW_WORKSPACE` 与 `--workspace` 一致 - 当前仓库默认围绕本地文件工作区设计，不依赖外部服务即可运行大多数能力 - 如果只修改文档，仍建议至少跑一遍 `status` 和相关 dry-run，确保示例命令没有漂移 ## 相关文档 - [`CHANGELOG.md`](CHANGELOG.md) - [`AGENTS.md`](AGENTS.md) - [`docs/详细设计文档.md`](docs/详细设计文档.md)