📦 super-memori — 本地记忆助手

状态： v3 基线，当缺失 Python 语义依赖时，会报告健康状态下的语义降级。 本目录提供真实的 v3 基线命令面，保留旧行为作为遗留参考，并记录后续完整混合实现的确切路径，而不假装语义层在所有主机上始终活跃。

执行

面向弱模型 — 先读这里

你只有 4 个可用命令：

• query-memory.sh [--mode auto|exact|hybrid|learning|recent] — 查找过往知识
• memorize.sh — 保存有用经验
• index-memory.sh — 刷新索引并处理积压
• health-check.sh — 验证内存是否健康或降级

规则：

• 只能使用这 4 个公开命令及其文档化参数。
• 除非本技能明确指引，否则忽略目录内其他可执行文件。诸如 auto-learner.sh、index-daily.sh、embed-file.py、embed-raw-file.py、vector_fallback.py 及辅助 Python 模块均不属于弱模型公开接口。
• “本技能明确指引”仅指：(a) 本 SKILL.md 在当期维护步骤中写明“运行 <确切文件>”；(b) 本 SKILL.md 的清单步骤点名该文件；(c) 用户明确要求运行该文件。文档中的引用、示例、架构说明或目录列表不算。
• 当本技能说“读取参考文件”时，仅指查阅文档。文档内出现的文件名除非步骤明确写“运行 <文件>”，否则不是执行指令。
• 默认使用 query-memory.sh --mode auto，除非下方模式选择规则明确映射到其他公开模式。
• 若健康或查询输出提示降级，应如实告知，而非假装结果完整。
• 仅当经验能改变未来行为时才使用 memorize.sh。

内存健康合约

health-check.sh 是可信内存工作的守门人。预期状态值：

• OK — 词汇基线健康
• WARN — 降级但仍部分可用
• FAIL — 关键内存层不健康

降级模式诚实原则：

• 若 health-check.sh 返回 WARN，在依赖结果前先声明内存已降级。
• 若查询输出提示降级，将结果视为部分而非完整。
• 不得在降级时暗示语义完整性。
• 使用如下警告格式：

⚠️ MEMORY DEGRADED: <来自 health-check 或查询输出的原因>. Results are partial.

• 若 WARN 后仍继续，需明确声明：

⚠️ Continuing in degraded mode. Risk of incomplete results. Rollback path: .

重大内存手术前（策略编辑、索引变更、大规模重写、命令合约改动）：

• 运行 health-check.sh。
• 若状态为 FAIL，停止依赖内存的更改，先修复健康。
• 若状态为 WARN，仅在显式降级意识及回滚路径下继续。
• 确认 git 历史或备份在广泛编辑前可提供回滚。

核心立场

像操作系统组件一样构建内存，而非演示品。本技能的正确设计是：

• 文件是规范真相
• SQLite FTS5 处理精确/词汇检索
• Qdrant 处理语义检索
• 小型 CPU reranker 是可选质量提升，非根基
• 弱模型仅看到极小的公开接口

公开命令面（目标 v3）

弱模型只需这四个入口：

• query-memory.sh — 检索记忆
• memorize.sh — 写入有用的学习/纠正/经验
• index-memory.sh — 维护索引
• health-check.sh — 验证内存健康

其余均为内部实现细节、遗留材料或辅助代码，除非本技能明确指示维护任务，否则勿直接调用。

规范规则

• 勿将向量索引视为真相来源。 Markdown/文件保持规范。
• 勿要求模型手动选择后端。 query-memory.sh 内部决定 auto/exact/semantic/hybrid。
• 勿隐藏降级模式。 若语义宕机而词汇仍可用，应明确说明。
• 勿记录每一次失败。 仅捕获能教会未来行为的失败。
• 将学习内存视为草稿优先，非规范真相。 学习条目在提升为持久记忆前均为临时。
• 重大内存工作前，先查阅近期学习内存。 复用过往经验避免重蹈覆辙。
• 勿盲目变更内存策略。 重大更改前先验证健康并保留回滚路径。
• 勿承诺魔法。 若某层陈旧、缺失或部分，应明确说明。

检索合约（目标行为）

未来 v3 检索路径：

query → 过滤（类型、时间、标签、命名空间）  
     → 词汇检索（SQLite FTS5）  
     → 语义检索（Qdrant，可用/需要时）  
     → 融合  
     → 可选 rerank  
     → 去重/多样化  
     → 结果 + 警告 + 新鲜度状态  

默认模式

默认使用 query-memory.sh --mode auto。

健康集成： query-memory.sh 已在输出中提示降级状态。无需每次查询前都运行 health-check.sh。仅在重大内存手术前、可疑行为后或需确认降级结果是否仍可信时使用 health-check.sh。

模式选择规则（优先级自上而下）

• 精确匹配信号 → query-memory.sh --mode exact

- 字面路径、配置键、服务名、引号字符串、错误信息、代码标识符

• 时间邻近信号 → query-memory.sh --mode recent

- recent、today、yesterday、last hour、last day、last week

• 学习信号 → query-memory.sh --mode learning

- lesson、mistake、failure、what did we learn

• 其他所有 → query-memory.sh --mode auto

- 类似过往问题、相关历史、基于含义的回忆、开放式记忆提问

平局规则： 若查询匹配多条信号，使用上述最高优先级的模式。 除非调试检索管道作为维护任务，否则勿直接调用 --mode hybrid。

写入/学习合约（目标行为）

仅当新信息可能帮助未来运行时，才使用 memorize.sh。

学习内存的用途

学习内存是自我改进的草稿区：

• 可复用的失败
• 纠正措施
• 经验教训
• 反复出现的反模式
• 有意义的能力缺口

学习内存默认非持久真相，需经重复复用或显式永久信号后才提升。

重大内存工作前

以下视为重大工作：

• 修改内存策略或检索行为
• 变更索引、健康或命令合约
• 重试已失败多次的内存任务
• 编辑本技能的 SKILL.md、参考文件或公开脚本

步骤：

• 运行 health-check.sh 并确认对被改文件存在回滚路径。
• 运行 query-memory.sh --mode learning --limit 5。
• 复用任何明显匹配的经验。
• 若无学习结果，正常继续。

良好候选

• 意外失败且经验可复用
• 用户纠正改变了未来行为
• 更好的可重复流程
• 反复出现的反模式
• 有意义的知识缺口

不良候选

• 预期的无匹配结果
• 一次性噪音
• 弱猜测
• 已记录的重复经验
• checked, nothing relevant

提升为持久内存

勿执行提升。 提升是未来/手动流程，非当前 v3 基线的自动化命令。 对本技能：

• memorize.sh 写入仅进入学习内存
• 弱模型不得发明提升命令
• 弱模型不得在普通 memorize.sh 流中自动重写持久内存
• 若学习看似值得永久保留，仅说：

Learning <摘要> appears valuable for later manual promotion.

• 到此为止

持久目标映射（未来/手动提升）

未来/手动层才允许提升到程序或语义内存。人工批准后可按以下映射：

• 可重复命令/调试步骤 → 程序内存
• 反模式/事后分析 → 程序经验内存
• 持久事实/偏好/基础设施事实 → 语义内存
• 带理由的决策 → 语义决策内存

反模式

• 勿自动记录每个非零退出码。
• 勿在多条学习记录中重复同一经验。
• 勿将一次性上下文提升为持久内存。
• 勿在无人工动作下尝试提升学习。
• 勿发明提升命令。
• 勿记录“未找到相关内容”。

健康/新鲜度合约

健康不仅指索引。健康还意味着代理能诚实判断学习内存是否被真正使用而非倾倒场，降级模式是否可安全继续，以及主机环境是否仍支持可信内存工作。

health-check.sh 当前至少报告：

• 规范文件可读
• 词汇索引状态
• 语义索引状态
• 队列积压
• 上次成功索引更新/新鲜度状态
• 降级状态

高级检查（重复/孤立风险）属于更完整语义层，在运行支持到位前不应声称存在。

query-memory.sh 当前至少报告：

• mode_requested
• mode_used
• degraded
• warnings[]
• index_fresh
• results[]

内存安全操作规则

• 遵循内存健康合约中的 WARN vs FAIL 规则后再依赖结果。
• 重大内存手术前，确认回滚路径存在且可访问（git status、备份目录列表或已验证的规范文件副本）。
• 优先对索引、健康脚本和检索合约做可逆更改。
• 勿在未经明确批准的情况下安排定期维护或审计。

学习内存在 super_memori 内的定位

学习内存是受控草稿层：

• memorize.sh 写入有用经验
• query-memory.sh --mode learning 检索它们
• 重复或关键经验未来可通过手动提升层进入程序或语义内存
• 提升前，学习内存保持临时而非规范

这让自我改进留在内存系统内，同时避免每条临时经验都变成永久真相。

当前目录含义

本技能现分两层：

1. 当前 v3 基线命令（技能根目录已实现的词汇优先运行时）

这些是活跃公开入口：

• query-memory.sh
• memorize.sh
• index-memory.sh
• health-check.sh

它们实现词汇优先 v3 公开面，带健康报告、队列/新鲜度状态，并对语义层诚实降级。

2. 遗留基线（scripts/legacy/ + 旧辅助文件）

保留旧 v2 时代行为及语义实验，作为迁移/参考材料。

3. v3 设计参考

这些参考定义后续 3.1.x 完整混合就绪规范及通往 4.0.0 的路径。重大更改前请先阅读：

• references/architecture.md — 目标架构
• references/command-contracts.md — CLI 合约与退出码
• references/retrieval-pipeline.md — 排序/融合/降级行为
• references/health-model.md — 本地内存的健康含义
• references/weak-model-guidance.md — 如何保持接口对弱模型安全
• references/migration-plan.md — 从遗留 v2 脚本迁移到 v3 的方法
• references/full-hybrid-mode.md — 声明完整混合模式前必须满足的条件
• references/implementation-order.md — 完成后续混合模式的精确弱模型安全顺序
• references/release-status.md — 版本标签含义
• references/roadmap-to-4.0.0.md — 完成后继运行时混合发布的简短指令

后续如何达成完整混合

勿跳过步骤。

• [ ] health-check.sh --json 显示词汇基线健康
• [ ] 语义依赖已安装并验证
• [ ] 规范文件的语义索引路径已实现
• [ ] 语义新鲜度/积压状态可见
• [ ] query-memory.sh --mode hybrid 融合词汇 + 语义结果
• [ ] 最后添加 reranker，作为可选质量层
• [ ] 健康、检索与文档一致后再发布任何 4.0.0

备份/暴露/风险说明

• 若索引降级或语义依赖消失，文件仍是规范恢复路径。
• 若主机远程、暴露或备份不足，优先计划先行而非直接编辑内存脚本。
• 若备份或快照未知，假设谨慎并避免不可逆清理。
• 本技能的健康指导仅覆盖内存可靠性，非完整主机加固。使用 healthcheck 做更广泛的主机安全决策。

今日如何使用本技能

若需当前内存行为

使用活跃根命令：

• query-memory.sh
• memorize.sh
• index-memory.sh
• health-check.sh

若需改进本技能

按此顺序：

• 运行 health-check.sh
• 若任务重大或曾失败，查阅近期学习内存
• 确认回滚是否存在（git、备份、未动过的规范文件）
• 阅读 references/architecture.md
• 阅读 references/command-contracts.md
• 阅读 references/migration-plan.md
• 再修补或替换脚本
• 修补后重新运行健康检查

勿做事项

• 勿在语义依赖与健康检查实际通过前声称语义检索已完全活跃
• 勿为弱模型增加更多公开命令
• 勿让 Qdrant 成为规范来源
• 勿让仅词汇降级模式静默失败
• 勿将每个非零退出码自动记为经验
• 勿在未经明确批准下安排定期检查或维护
• 勿将架构说明混回公开命令接口

设计目标

目标不是“最花哨的内存系统”，而是：

弱模型在仅 CPU 的 Ubuntu OpenClaw 主机上可可靠使用的最强本地内存技能

这就是 v3 的门槛。

版本解读

• 3.0.x = 可工作的词汇优先 v3 基线，带受监控的语义降级
• 3.1.x = 完整混合就绪技能规范，以便弱模型后续按受控顺序完成语义栈；此为文档/规范成熟度状态，非运行时激活
• 4.0.0 = 仅在运行时验证的完整混合模式实际实现并测试后

关于后续下一步指令，请阅读 references/roadmap-to-4.0.0.md。