核心用法
Persistent Memory 是一套为 OpenClaw 工作空间设计的三层持久化记忆架构，解决 AI 代理"重启即失忆"的核心痛点。系统通过 L1 Markdown（人工可读知识库）、L2 向量层（ChromaDB 语义检索）、L3 图谱层（NetworkX 关系推理）的协同，实现跨会话的决策保留、事实记忆与上下文追溯。
典型使用场景：
- 代理需要回忆数周前的架构决策或用户偏好
- 维护团队共享的 institutional knowledge（人员、仓库、基础设施信息）
- 避免重复询问已确认过的外部标识符（URL、邮箱、仓库名）
- 建立可追溯的项目演进日志
关键操作：通过 setup.sh 初始化环境，日常编辑 MEMORY.md（长期知识）、memory/YYYY-MM-DD.md（每日日志）、reference/*.md（机构百科）后，必须运行 indexer.py 同步三层；查询时使用 search.py 进行语义检索，或让代理通过 auto_retrieve.py 自动获取上下文。
显著优点
1. 架构完整性：三层设计兼顾人类可维护性（Markdown）与机器检索效率（向量+图谱），是少数同时满足"人可读"与"机可用"的记忆方案
2. 零外部依赖：纯本地部署（Python + ChromaDB + NetworkX），无云 API 调用，数据完全自控
3. 防幻觉机制：强制代理在回答历史问题前检索记忆，在引用外部标识符前核对 reference/ 文件，从流程上杜绝编造
4. 渐进式积累：每日日志自动归档，机构知识随时间沉淀，代理能力随项目持续增强
5. 开放生态：文件即数据，可用任意 Git 工具版本控制，便于团队协作与审计
潜在缺点与局限性
- 维护负担：每次编辑记忆文件后需手动重索引，容易遗忘导致"记忆滞后"
- 技术门槛：需要理解向量检索与知识图谱的基本概念，调试索引问题需一定 ML 背景（如 SIGSEGV 报错涉及库版本兼容）
- 规模瓶颈：本地 ChromaDB 与 NetworkX 适合项目级记忆，PB 级数据或需迁移至专用向量数据库
- 冷启动问题：新项目初期记忆空白，代理仍需频繁询问用户
- 语义漂移：Embedding 模型（all-MiniLM-L6-v2）对专业术语的理解可能与人类意图存在偏差
适合人群
- 长期运行的 AI 辅助项目（数周至数月周期）
- 多代理协作或人机协同的复杂工作空间
- 对数据隐私敏感、拒绝云记忆方案的团队
- 需要可审计、可版本控制的记忆系统的合规场景
常规风险
- 索引遗忘风险：未执行
indexer.py导致记忆层不一致，代理可能给出过时答案 - 文件污染风险：
memory/目录下的每日日志若无定期清理，可能累积噪声干扰检索 - 版本冲突风险：多人协作时若同时修改
MEMORY.md并分别索引，可能产生图谱不一致 - 模型锁定风险：Embedding 模型固定在 setup 脚本中，未来难以无痛升级至更强模型