增强型记忆系统

OpenClaw 记忆系统的即插即用式增强模块。以四信号混合检索流水线替代原有的扁平向量搜索，MRR 达到 0.782（基线纯向量检索约为 0.45）。

安装配置

# 安装 Ollama 并拉取嵌入模型
ollama pull nomic-embed-text

# 索引你的记忆文件（请在 workspace 根目录下执行）
python3 skills/enhanced-memory/scripts/embed_memories.py

# 可选：构建跨引用图谱
python3 skills/enhanced-memory/scripts/crossref_memories.py build

当 memory 文件发生显著变更时，请重新运行 embed_memories.py。

脚本说明

scripts/search_memory.py — 主检索脚本

具备自动适配能力的四信号混合检索：

python3 skills/enhanced-memory/scripts/search_memory.py "query" [top_n]

融合的四大信号：

1. 向量相似度（权重 0.4）—— 基于 nomic-embed-text 嵌入向量的余弦相似度
2. 关键词匹配（权重 0.25）—— 查询词与文本块内容的重叠程度
3. 标题匹配（权重 0.1）—— 查询词是否出现在章节标题中
4. 路径评分（权重 0.25）—— 查询词与文件名或目录名的匹配程度

自动行为特性：

• 时间路由（Temporal routing）—— 对包含日期指代（如“昨天”、“2 月 8 日”、“上周一”）的查询，匹配文件得分提升至 3 倍
• 自适应加权（Adaptive weighting）—— 当关键词重叠率较低时，自动将向量权重提升至 85%
• 伪相关反馈（Pseudo-relevance feedback, PRF）—— 当最高得分低于 0.45 时，从初始结果中提取扩展词项重构查询，并重新打分

scripts/enhanced_memory_search.py — JSON 兼容检索

采用相同检索流程，输出格式为 JSON，与 OpenClaw 的 memory_search 工具兼容：

python3 skills/enhanced-memory/scripts/enhanced_memory_search.py --json "query"

返回结构：{results: [{path, startLine, endLine, score, snippet, header}], ...}。

scripts/embed_memories.py — 索引构建

对 memory/ 目录下所有 .md 文件，以及核心 workspace 文件（如 MEMORY.md、AGENTS.md 等），按 Markdown 标题切分文本块并完成嵌入：

python3 skills/enhanced-memory/scripts/embed_memories.py

输出文件为 memory/vectors.json。嵌入过程按每批 20 条进行批量处理，单个文本块截断长度为 2000 字符。

scripts/memory_salience.py — 显著性评分

识别陈旧/重要记忆条目，用于心跳机制下的自提示（self-prompting）：

python3 skills/enhanced-memory/scripts/memory_salience.py          # 生成人类可读提示
python3 skills/enhanced-memory/scripts/memory_salience.py --json   # 输出结构化 JSON
python3 skills/enhanced-memory/scripts/memory_salience.py --top 5  # 返回更多条目

评分公式为 importance × staleness，综合考量：文件类型（主题类 > 核心类 > 日常类）、文件大小、访问频率及与历史查询间隔的相关性。

scripts/crossref_memories.py — 知识图谱构建

基于嵌入相似度，在记忆文本块之间建立跨引用链接：

python3 skills/enhanced-memory/scripts/crossref_memories.py build          # 构建索引
python3 skills/enhanced-memory/scripts/crossref_memories.py show     # 查看某文件的引用关系
python3 skills/enhanced-memory/scripts/crossref_memories.py graph          # 输出图谱统计信息

采用“文件代表性”策略（每文件选取 top 5 文本块为代表），将原始 O(n²) 复杂度降至可管理规模。相似度阈值设定为 0.75（余弦相似度）。

配置参数

所有可调常量均位于各脚本顶部。关键参数如下：

若需更换嵌入模型（例如使用 mxbai-embed-large），请修改各脚本中的 MODEL 常量，并重新运行 embed_memories.py。

集成方式

如需替换默认记忆检索功能，请将 agent 的搜索工具指向上述脚本。这些脚本依赖以下前提条件：

• workspace 根目录下存在 memory/ 目录，其中包含若干 .md 文件
• 已通过 embed_memories.py 生成 memory/vectors.json
• Ollama 在本地 11434 端口运行

所有脚本仅依赖 Python 标准库及 Ollama HTTP API，无需额外 pip 安装依赖。