Jasper Recall

# Jasper Recall v0.2.3

本地 RAG（检索增强生成）系统，用于 AI 智能体记忆。赋予您的智能体记住和搜索过往对话的能力。

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

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

**v0.2.0 新增：** 共享智能体记忆 —— 主智能体与沙盒智能体之间双向学习，并具备隐私控制。

## 使用场景

- **记忆召回**：在回答之前搜索过往会话以获取上下文 - **持续学习**：为未来的参考索引每日笔记和决策 - **会话连续性**：记住重启期间发生的事情 - **知识库**：根据您的智能体经验构建可搜索的文档

## 快速开始

### 设置

一条命令即可安装所有内容：

```bash npx jasper-recall setup ```

这将创建： - 位于 `~/.openclaw/rag-env` 的 Python venv - 位于 `~/.openclaw/chroma-db` 的 ChromaDB 数据库 - `~/.local/bin/` 中的 CLI 脚本 - `openclaw.json` 中的 OpenClaw 插件配置

### 为什么选择 Python？

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

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

这些是本地 RAG 的黄金标准。没有能在完全离线状态下良好运行的 Node.js 同类产品。

### 为什么使用独立的 Venv？

位于 `~/.openclaw/rag-env` 的 venv 提供：

| 优势 | 为何重要 | |---------|----------------| | **隔离性** | 不会与您的其他 Python 项目冲突 | | **无需 sudo** | 安装到您的主目录，无需 root 权限 | | **彻底卸载** | 删除文件夹即可移除 | | **可复现性** | 到处都是相同的版本 |

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

### 基本用法

**搜索您的记忆：** ```bash recall "what did we decide about the API design" recall "hopeIDS patterns" --limit 10 recall "meeting notes" --json ```

**索引您的文件：** ```bash index-digests # Index memory files into ChromaDB ```

**创建会话摘要：** ```bash digest-sessions # Process new sessions digest-sessions --dry-run # Preview what would be processed ```

## 工作原理

### 三个组件

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

## 智能体集成

### 记忆增强响应

```python # Before answering questions about past work results = exec("recall 'project setup decisions' --json") # Include relevant context in your response ```

### 自动索引（心跳）

添加到 HEARTBEAT.md： ```markdown ## Memory Maintenance - [ ] New session logs? → `digest-sessions` - [ ] Memory files updated? → `index-digests` ```

### Cron 任务

安排定期索引： ```json { "schedule": { "kind": "cron", "expr": "0 */6 * * *" }, "payload": { "kind": "agentTurn", "message": "Run index-digests to update the memory index" }, "sessionTarget": "isolated" } ```

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

适用于沙盒智能体需要访问某些记忆的多智能体设置：

### 记忆标记

在每日笔记中标记条目：

```markdown ## 2026-02-05 [public] - Feature shipped This is visible to all agents.

## 2026-02-05 [private] - Personal note This is main agent only (default if untagged).

## 2026-02-05 [learning] - Pattern discovered Learnings shared bidirectionally between agents. ```

### ChromaDB 集合 (v0.2.2+)

记忆存储在独立的集合中以实现隔离：

| 集合 | 用途 | 访问者 | |------------|---------|--------------| | `private_memories` | 主智能体的私有内容 | 仅主智能体 | | `shared_memories` | [public] 标记的内容 | 沙盒智能体 | | `agent_learnings` | 来自任何智能体的学习内容 | 所有智能体 | | `jasper_memory` | 传统统一（向后兼容） | 回退选项 |

**集合选择：** ```bash # Main agent (default) - searches private_memories recall "api design"

# Sandboxed agents - searches shared_memories only recall "product info" --public-only

# Search learnings only recall "patterns" --learnings

# Search all collections (merged results) recall "everything" --all

# Specific collection recall "something" --collection private_memories

# Legacy mode (single collection) recall "old way" --legacy ```

### 沙盒智能体访问

```bash # Sandboxed agents use --public-only recall "product info" --public-only

# Main agent can see everything recall "product info" ```

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

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

```bash # Configure sandboxed agent with --public-only restriction npx jasper-recall moltbook-setup

# Verify the setup is correct npx jasper-recall moltbook-verify ```

这将创建： - `~/bin/recall` — 强制使用 `--public-only` 标志的包装器 - `shared/` — 指向主工作区共享内存的符号链接

然后，沙盒智能体可以使用： ```bash ~/bin/recall "query" # Automatically restricted to public memories ```

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

### 隐私工作流

```bash # Check for sensitive data before sharing privacy-check "text to scan" privacy-check --file notes.md

# Extract [public] entries to shared directory sync-shared sync-shared --dry-run # Preview first ```

## CLI 参考

### recall

``` recall "query" [OPTIONS]

Options: -n, --limit N Number of results (default: 5) --json Output as JSON -v, --verbose Show similarity scores and collection source --public-only Search shared_memories only (sandboxed agents) --learnings Search agent_learnings only --all Search all collections (merged results) --collection X Search specific collection by name --legacy Use legacy jasper_memory collection ```

### serve (v0.2.1+)

``` npx jasper-recall serve [OPTIONS]

Options: --port, -p N Port to listen on (default: 3458) --host, -h H Host to bind (default: 127.0.0.1)

Starts HTTP API server for Docker-isolated agents.

Endpoints: GET /recall?q=query&limit=5 Search memories GET /health Health check

Security: public_only=true enforced by default. Set RECALL_ALLOW_PRIVATE=true to allow private queries. ```

**示例（来自 Docker 容器）：** ```bash curl "http://host.docker.internal:3458/recall?q=product+info" ```

### privacy-check (v0.2.0+)

``` privacy-check "text" # Scan inline text privacy-check --file X # Scan a file

Detects: emails, API keys, internal IPs, home paths, credentials. Returns: CLEAN or list of violations. ```

### sync-shared (v0.2.0+)

``` sync-shared [OPTIONS]

Options: --dry-run Preview without writing --all Process all daily notes

Extracts [public] tagged entries to memory/shared/. ```

### index-digests

``` index-digests

Indexes markdown files from: ~/.openclaw/workspace/memory/*.md ~/.openclaw/workspace/memory/session-digests/*.md ~/.openclaw/workspace/memory/repos/*.md ~/.openclaw/workspace/memory/founder-logs/*.md

Skips files that haven't changed (content hash check). ```

### digest-sessions

``` digest-sessions [OPTIONS]

Options: --dry-run Preview without writing --all Process all sessions (not just new) --recent N Process only N most recent sessions ```

## 配置

### 自定义路径

设置环境变量：

```bash 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`（仅限本地主机）。**请勿使用 `--host 0.0.0.0`**，除非您明确打算对外暴露 API 并已采取了适当的安全措施。

### 私有记忆访问

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

### autoRecall 插件

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

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

**自动跳过的内容（不触发 recall）：** - 心跳轮询（`HEARTBEAT`、`Read HEARTBEAT.md`、`HEARTBEAT_OK`） - 包含 `NO_REPLY` 的消息 - 少于 10 个字符的消息 - 智能体到智能体的消息（Cron 任务、工作进程、生成的智能体） - 自动报告（`📋 PR Review`、`🤖 Codex Watch`、`ANNOUNCE_*`） - 来自以 `agent:` 或 `worker-` 开头发送者的消息

**不受信任上下文的更安全配置：** ```json "jasper-recall": { "enabled": true, "config": { "autoRecall": true, "publicOnly": true, "minScore": 0.5 } } ```

### 环境变量

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

| 变量 | 默认值 | 用途 | |----------|---------|---------| | `RECALL_WORKSPACE` | `~/.openclaw/workspace` | 记忆文件位置 | | `RECALL_CHROMA_DB` | `~/.openclaw/chroma-db` | 向量数据库路径 | | `RECALL_SESSIONS_DIR` | `~/.openclaw/agents/main/sessions` | 会话日志 | | `RECALL_ALLOW_PRIVATE` | `false` | 服务器私有访问权限 | | `RECALL_PORT` | `3458` | 服务器端口 | | `RECALL_HOST` | `127.0.0.1` | 服务器绑定地址 |

### 先试运行

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

```bash privacy-check --file notes.md # Scan for sensitive data sync-shared --dry-run # Preview public extraction digest-sessions --dry-run # Preview session processing ```

### 沙盒环境

为了最大限度地隔离，请在容器或专用帐户中运行 jasper-recall： - 限制意外数据暴露的风险 - 将私有记忆与共享上下文分离 - 推荐用于包含不受信任智能体的多智能体设置

## 故障排除

**“未找到索引”** ```bash index-digests # Create the index first ```

**“未找到集合”** ```bash rm -rf ~/.openclaw/chroma-db # Clear and rebuild 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