名称： jasper-recall
版本： 0.3.1
描述： 基于 ChromaDB 和 sentence-transformers 的本地 RAG 智能体记忆系统。v0.3.0 新增多智能体网格（N 个智能体共享记忆）、带 autoRecall 的 OpenClaw 插件以及智能体专属集合。命令：recall, index-digests, digest-sessions, privacy-check, sync-shared, serve, recall-mesh。

Jasper Recall v0.2.3

本地 RAG（检索增强生成）系统，为 AI 智能体提供记忆功能。让你的智能体能够记住并搜索过去的对话。

v0.2.2 新增功能： 共享 ChromaDB 集合 — 为私有、共享和学习内容提供独立的集合。为多智能体设置提供更好的隔离。

v0.2.1 新增功能： 记忆服务器 — 为无法直接运行 CLI 的 Docker 隔离智能体提供 HTTP API。

v0.2.0 新增功能： 共享智能体记忆 — 在主智能体与沙箱智能体之间进行带隐私控制的双向学习。

使用场景

• 记忆检索：在回答问题前搜索历史会话以获取上下文
• 持续学习：索引每日笔记和决策以供未来参考
• 会话连续性：记住重启之间发生的事情
• 知识库：从智能体经验中构建可搜索的文档

快速开始

安装

一条命令完成所有安装：

npx jasper-recall setup

此命令将创建：
- Python 虚拟环境：~/.openclaw/rag-env
- ChromaDB 数据库：~/.openclaw/chroma-db
- CLI 脚本：~/.local/bin/
- OpenClaw 插件配置：openclaw.json

为什么使用 Python？

核心的搜索和嵌入功能使用 Python 库：

• ChromaDB — 用于语义搜索的向量数据库
• sentence-transformers — 本地嵌入模型（无需 API）

这些是本地 RAG 的黄金标准。目前没有功能完整且完全离线的 Node.js 替代方案。

为什么使用独立的虚拟环境？

位于 ~/.openclaw/rag-env 的虚拟环境提供：

依赖项较大（包含嵌入模型总计约 200MB），但这是一次性下载，完全在本地运行。

基础使用

搜索记忆：

recall "我们关于 API 设计决定了什么"
recall "hopeIDS 模式" --limit 10
recall "会议笔记" --json

索引文件：

index-digests  # 将记忆文件索引到 ChromaDB

创建会话摘要：

digest-sessions          # 处理新会话
digest-sessions --dry-run  # 预览将要处理的内容

工作原理

三个组件

1. digest-sessions — 从会话日志中提取关键信息（主题、使用的工具）
2. index-digests — 将 Markdown 文件分块并嵌入到 ChromaDB
3. recall — 对已索引的记忆进行语义搜索

索引内容

默认索引 ~/.openclaw/workspace/memory/ 目录下的文件：

• *.md — 每日笔记，MEMORY.md
• session-digests/*.md — 会话摘要
• repos/*.md — 项目文档
• founder-logs/*.md — 开发日志（如果存在）

嵌入模型

使用 sentence-transformers/all-MiniLM-L6-v2：
- 384 维嵌入向量
- 首次运行下载约 80MB
- 本地运行，无需 API

智能体集成

记忆增强响应

# 在回答关于过去工作的问题之前
results = exec("recall '项目设置决策' --json")
# 在响应中包含相关上下文

自动索引（心跳）

添加到 HEARTBEAT.md：

## 记忆维护
- [ ] 有新会话日志？ → `digest-sessions`
- [ ] 记忆文件已更新？ → `index-digests`

定时任务

安排定期索引：

{
  "schedule": { "kind": "cron", "expr": "0 */6 * * *" },
  "payload": {
    "kind": "agentTurn",
    "message": "运行 index-digests 以更新记忆索引"
  },
  "sessionTarget": "isolated"
}

共享智能体记忆 (v0.2.0+)

适用于沙箱智能体需要访问部分记忆的多智能体设置：

记忆标记

在每日笔记中标记条目：

## 2026-02-05 [public] - 功能已发布
所有智能体可见。

## 2026-02-05 [private] - 个人笔记
仅主智能体可见（未标记时的默认值）。

## 2026-02-05 [learning] - 发现的模式
智能体之间双向共享的学习成果。

ChromaDB 集合 (v0.2.2+)

记忆存储在独立的集合中以确保隔离：

集合选择：

# 主智能体（默认） - 搜索 private_memories
recall "api 设计"

# 沙箱智能体 - 仅搜索 shared_memories
recall "产品信息" --public-only

# 仅搜索学习成果
recall "模式" --learnings

# 搜索所有集合（合并结果）
recall "所有内容" --all

# 搜索特定集合
recall "某事" --collection private_memories

# 旧版模式（单一集合）
recall "旧方式" --legacy

沙箱智能体访问

# 沙箱智能体使用 --public-only
recall "产品信息" --public-only

# 主智能体可以查看所有内容
recall "产品信息"

Moltbook 智能体设置 (v0.4.0+)

对于 moltbook-scanner（或任何沙箱智能体），使用内置设置：

# 使用 --public-only 限制配置沙箱智能体
npx jasper-recall moltbook-setup

# 验证设置是否正确
npx jasper-recall moltbook-verify

此命令将创建：
- ~/bin/recall — 强制使用 --public-only 标志的包装器
- shared/ — 指向主工作空间共享记忆的符号链接

沙箱智能体随后可以使用：

~/bin/recall "查询"  # 自动限制为公共记忆

隐私模型：
1. 主智能体在每日笔记中将记忆标记为 [public] 或 [private]
2. sync-shared 将 [public] 内容提取到 memory/shared/
3. 沙箱智能体只能搜索 shared 集合

隐私工作流

# 在共享前检查敏感数据
privacy-check "要扫描的文本"
privacy-check --file notes.md

# 将 `[public]` 条目提取到共享目录
sync-shared
sync-shared --dry-run  # 先预览

CLI 参考

recall

recall "查询" [选项]

选项：
  -n, --limit N     结果数量（默认：5）
  --json            输出为 JSON 格式
  -v, --verbose     显示相似度分数和集合来源
  --public-only     仅搜索 shared_memories（沙箱智能体）
  --learnings       仅搜索 agent_learnings
  --all             搜索所有集合（合并结果）
  --collection X    按名称搜索特定集合
  --legacy          使用旧版 jasper_memory 集合

serve (v0.2.1+)

npx jasper-recall serve [选项]

选项：
  --port, -p N    监听的端口（默认：3458）
  --host, -h H    绑定的主机（默认：127.0.0.1）

为 Docker 隔离的智能体启动 HTTP API 服务器。

端点：
  GET /recall?q=查询&limit=5    搜索记忆
  GET /health                   健康检查

安全：默认强制执行 public_only=true。
设置 RECALL_ALLOW_PRIVATE=true 以允许私有查询。

示例（从 Docker 容器中）：

curl "http://host.docker.internal:3458/recall?q=产品+信息"

privacy-check (v0.2.0+)

privacy-check "文本"     # 扫描内联文本
privacy-check --file X   # 扫描文件

检测内容：电子邮件、API 密钥、内部 IP、主目录路径、凭据。
返回：CLEAN 或违规列表。

sync-shared (v0.2.0+)

sync-shared [选项]

选项：
  --dry-run    预览而不写入
  --all        处理所有每日笔记

将标记为 `[public]` 的条目提取到 memory/shared/。

index-digests

index-digests

索引来自以下目录的 Markdown 文件：
  ~/.openclaw/workspace/memory/*.md
  ~/.openclaw/workspace/memory/session-digests/*.md
  ~/.openclaw/workspace/memory/repos/*.md
  ~/.openclaw/workspace/memory/founder-logs/*.md

跳过未更改的文件（内容哈希检查）。

digest-sessions

digest-sessions [选项]

选项：
  --dry-run    预览而不写入
  --all        处理所有会话（不仅仅是新会话）
  --recent N   仅处理最近的 N 个会话

配置

自定义路径

设置环境变量：

export RECALL_WORKSPACE=~/.openclaw/workspace
export RECALL_CHROMA_DB=~/.openclaw/chroma-db
export RECALL_SESSIONS_DIR=~/.openclaw/agents/main/sessions

分块

index-digests 中的默认设置：
- 块大小：500 个字符
- 重叠：100 个字符

安全注意事项

⚠️ 在生产环境中启用前，请仔细审查以下设置：

服务器绑定

serve 命令默认绑定到 127.0.0.1（仅限本地主机）。除非你明确打算将 API 暴露给外部并已做好适当的安全防护，否则不要使用 --host 0.0.0.0。

私有记忆访问

服务器默认强制执行 public_only=true。环境变量 RECALL_ALLOW_PRIVATE=true 可以绕过此限制。切勿在公共/共享主机上设置此变量 — 这会将你的私有记忆暴露给任何客户端。

autoRecall 插件

当 OpenClaw 插件配置中 autoRecall: true 时，记忆会在每条智能体消息前自动注入。请考虑：

• 为沙箱智能体在插件配置中设置 publicOnly: true
• 审查将搜索哪些集合
• 使用 minScore 过滤低相关性注入

以下情况会自动跳过（不触发 recall）：
- 心跳轮询（HEARTBEAT, Read HEARTBEAT.md, HEARTBEAT_OK）
- 包含 NO_REPLY 的消息
- 长度小于 10 个字符的消息
- 智能体间消息（定时任务、工作进程、衍生的智能体）
- 自动化报告（📋 PR Review, 🤖 Codex Watch, ANNOUNCE_*）
- 来自以 agent: 或 worker- 开头发送者的消息

用于不受信任环境的更安全配置：

"jasper-recall": {
  "enabled": true,
  "config": {
    "autoRecall": true,
    "publicOnly": true,
    "minScore": 0.5
  }
}

环境变量

以下环境变量会影响行为 — 请显式设置它们，而不是依赖默认值：

先进行试运行

在共享或同步之前，使用试运行选项预览将要暴露的内容：

privacy-check --file notes.md     # 扫描敏感数据
sync-shared --dry-run             # 预览公共内容提取
digest-sessions --dry-run         # 预览会话处理

沙箱环境

为了获得最大隔离性，请在容器或专用账户中运行 jasper-recall：
- 降低意外数据暴露的风险
- 将私有记忆与共享上下文分离
- 建议用于包含不受信任智能体的多智能体设置

故障排除

“未找到索引”

index-digests  # 首先创建索引

“未找到集合”

rm -rf ~/.openclaw/chroma-db  # 清除并重建
index-digests

模型下载缓慢
首次运行会下载约 80MB 的模型。后续运行是即时的。

链接

• GitHub: https://github.com/E-x-O-Entertainment-Studios-Inc/jasper-recall
• npm: https://www.npmjs.com/package/jasper-recall
• ClawHub: https://clawhub.ai/skills/jasper-recall