# @bastra-recall/daemon 中文文档

规范地址：https://npmcn.com/package/%40bastra-recall/daemon/

版本：1\.1\.8
npm 元数据更新时间：2026-10-31T14:12:51.234Z
中文译文更新时间：2026-10-31T16:17:08.361Z
软件包许可：MIT

本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40bastra-recall/daemon
原文对照：https://npmcn.com/package/%40bastra-recall/daemon/?lang=original
项目主页：https://bastra.io/
源码仓库：https://github.com/n0mad-ai/bastra-recall

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：9.5 MB，983 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=22
- 运行依赖：6 个
- 首次发布：2026-06-23T04:52:28.391Z
- 最新版本发布：2026-10-31T14:12:50.826Z
- 已发布版本数：27（近 12 个月 27 个）

## 中文简介

MCP服务器在markdown vault上：recall， load\_memory, save\_memory, edit\_memory， archive\_memory和文档工具-加上REST网关，安静的钩子通道和基础命令行。

## 安装

```sh
npm install @bastra-recall/daemon
```

也可以使用：`pnpm add @bastra-recall/daemon`、`yarn add @bastra-recall/daemon`、`bun add @bastra-recall/daemon`

## README

# @bastra-recall /守护进程

MCP服务器+ HTTP网关后面的基础架构召回。观察markdown vault，使用BM25 +可选嵌入对其进行索引，并在studio MCP和HTTP REST上公开稳定的工具表面。

有关项目级文档（远景、安装、REST API、路线图），请参阅 [顶级的自述](https://npmcn.com/package/README.md) 和 [PLAN.md](https://npmcn.com/package/PLAN.md).

## 它是做什么的

-   监视的目录 `.md` 带有YAML前文（模式）的文件 [`../../docs/memory-schema.md`](https://npmcn.com/package/docs/memory-schema.md)）。
-   索引通过 [`minisearch`](https://github.com/lucaong/minisearch) BM25; `recall_when` 是权重最高的场因为它是用来触发的。
-   **混合的回忆**：可选的嵌入（Ollama或OpenAI），通过BM25之上的互惠等级融合-见 `BASTRA_EMBEDDING_PROVIDER`.
-   **保存路径**:写 `.md` 文件，验证前页（zod），强制索引，使保存+召回在同一回合是一致的。
-   **汽车相关浓缩器**：对于每一个新的保存，填充 `related_via` 邻域余弦≥0.7。
-   **内存图**：多跳召回(`expand_hops: 1`)通过返回1跳邻居 `related_via`.
-   **灵敏度过滤器**： `private` 内存对外部MCP/REST调用者是不可见的-并且由于#464也不能被他们写入。该权限绑定到传输，而不是作为工具参数传递，并且拒绝读和拒绝写的回答都是一样的，因此两者都不是存在预言。
-   **过时评估**：回忆 `valid_until` / `expires_after_days` / `last_reviewed_at` 在召回时被降级（或被排除，如果过期）。

## 表面

| 表面 | 入口点 | 用例 |
| --- | --- | --- |
| MCP（工作室，单机） | `dist/index.js` | 客户端设置;每个会话都会生成自己的嵌入式守护进程 |
| MCP转发器（stdio→loopback HTTP） | `dist/mcp-forwarder.js` | **多客户端设置的默认值。** 按需启动丢失的守护进程，首先给已安装的托管macOS服务最多10秒的时间。所有会话共享一个保险库状态、一个索引、一个遥测流 |
| HTTP REST | `http://127.0.0.1:6723/api/v1/{tool}` | 非mcp客户端（web应用程序，脚本，传统自定义GPT操作）。支持承载认证+ CORS |
| 基于HTTP的MCP | `POST /api/v1/mcp` （可流HTTP，无状态） | 远程客户端，如ChatGPT web/phone和claude。ai，通过您自己的HTTPS隧道。承载令牌或守护进程自己的OAuth 2.1登录。 [远程访问](https://npmcn.com/package/docs/REMOTE-ACCESS.md) |
| 钩子 | `dist/hook.js` (PreToolUse), `dist/session-hook.js` (SessionStart) | 两者都POST到守护进程 `/hook/recall` |
| 命令行界面 | `dist/cli.js` （`bastra` 本) | 在每个支持的AI客户端上安装/卸载/医生 |

## 公开的工具（MCP + REST对称）

| 工具 | 目的 |
| --- | --- |
| `recall(query, k?, scope?, type?, expand_hops?)` | 搜查金库；启用时的混合BM25 +嵌入 |
| `load_memory(id)` | 取完整的前体+体 |
| `save_memory({title, type, body, …})` | 用模式验证+强制索引写一个新的内存 |
| `edit_memory({id, str_replace?, append?, frontmatter?, expected_revision?})` | 通过相同的保存路径修补一个现有内存（#519） |
| `find_document(query, k?)` | 搜寻文件（pdf、相片、合约） |
| `read_document(id)` | 为文档加载提取的文本+元数据 |
| `open_document(id)` | macOS-only：在系统处理程序中打开 |
| `find_code(query, mode?, repo?, depth?)` | 在代码图中定位符号或文件；一跳的家属（#576） |
| `save_document` / `recategorize_document` / `move_document` | 文档写入路径(Pro mac应用程序使用这个；OSS调用者可能需要 `BASTRA_DOCUMENT_WRITE=1`） |

## 安装+注册

看到 [顶级的自述](https://npmcn.com/package/README.md)． 路径，按摩擦的顺序：

1.  **`curl -fsSL https://bastra.io/install | bash`** -安装Homebrew + tap + binary +运行引导安装。推荐的非开发人员路径。
2.  **`Install Bastra.command` 双击** -相同的步骤，但浏览器下载被隔离并且模式为644，因此需要右键单击→打开（#320）。
3.  **`bastra install all`** -单个CLI调用，注册MCP + Skill +默认的静默钩子，横跨Claude Code， Claude Desktop， Codex/ChatGPT Desktop和Cursor。在没有配置保险库的情况下首次运行时，将提供一个交互式安装来创建 `~/BastraVault` 为你(非互动/`--yes`/`--dry-run` 运行保持确定性错误)。
4.  **完全手动的JSON片段** -回退。

所有路径都以客户端配置补丁结束。守护进程是否已经启动 **运行** 不同之处在于：交互式Map向导启动它，而MCP转发器在第一次工具调用时启动它 `bastra install all` 只注册，它既不启动也不检查守护进程的运行状况。 `bastra doctor` 探测端点（#525）。 使用 `bastra doctor --fix` 修复陈旧的路径，缺少所需的钩子，或一个 更新后的陈旧技能副本。默认情况下，CLI启用了安静的Stop save-eval钩子。选择退出 `bastra install claude-code --no-stop-hook`;故意禁用此选项 钩子不能使医生失败。

## 守护进程检查

不要抱怨 `daemon/dist/index.js` -守护进程通常以相对路径启动(`node dist/index.js`)，不会匹配。请使用端口：

```bash
lsof -i :6723 -P -n      # who owns the daemon port
curl -sS http://127.0.0.1:6723/health
```

应该只列出一个PID。Two表示一个过时的守护进程正在并行运行——HTTP端口先进入哪个绑定，失败的端口静默退出（参见HTTP -listen.ts中的EADDRINUSE处理程序）。

## 守护进程启动

MCP转发器使用一个共享守护进程，在回退产生之前为已安装的托管macOS服务提供最多10秒的时间。对于REST客户端 在MCP客户端连接之前需要守护进程，显式启动它：

```bash
bastra-recall &
```

## 开发工作流程

```bash
npm run dev                # ts-watch via tsx (no compile step)
npm run build              # tsc + chmod +x all dist binaries
npm run check:types        # type-check only
npm run smoke              # smoke-test recall against fixtures/sample-vault
npm run smoke:telemetry    # smoke-test telemetry append
npm run backfill:related   # populate related_via on legacy memories
```

## 配置（环境变量）

每个开/关开关都读出 `0`， `false`， `off` 或者 `no` 像off和 `1`， `true`， `on` 或者 `yes` 在任何情况下，都是这样；该表显示了规范拼写。

| env var | 要求 | 默认的 | 意义 |
| --- | --- | --- | --- |
| `BASTRA_VAULT_PATH` | 是 | \- - - - - - | 到保险库根的绝对路径（内存是自动发现的） |
| `BASTRA_HTTP_PORT` | 否 | `6723` | 用于REST +钩子的环回HTTP端口；只有当下面的URL变量都没有设置时才读取 |
| `BASTRA_HTTP_URL` | 否 | 派生的 | 完全URL覆盖（用于非环回测试）；只读 `BASTRA_DAEMON_URL` 是设置 |
| `BASTRA_API_TOKEN` | 否 | 设置 | 承载REST `/api/v1/*` 要求每个非直接本地呼叫者；unset/empty不会打开API——这样的调用者会得到一个 `401` 没有什么可以满足，直到一个令牌被铸造（#526） |
| `BASTRA_AUTH_LOOPBACK_SKIP` | 否 | `1` | 无令牌路径需要环回对等体 **和** 礼物，回环 `Host` 报头-丢失的报头被视为外部（#526）；设置为 `0` 即使是直接的127.0.0.1呼叫者也需要承载 |
| `BASTRA_CORS_ORIGIN` | 否 | 取消设置（拒绝所有） | 以逗号分隔的浏览器原点allowlist；Unset =不允许浏览器源； `*` = 显式许可选择加入 (隧道/dev) |
| `BASTRA_EMBEDDING_PROVIDER` | 否 | 设置 | `ollama` 或者 `openai`;如果没有它，守护进程将只支持bm25 |
| `BASTRA_EMBEDDING_MODEL` | 否 | 供应商违约 | 如。 `embeddinggemma` (ollama)或 `text-embedding-3-small` (openai) |
| `BASTRA_OLLAMA_URL` | 否 | `http://localhost:11434` | Ollama提供程序端点 |
| `BASTRA_ALLOW_REMOTE_OLLAMA` | 否 | 设置 | 允许非环回 `BASTRA_OLLAMA_URL`;如果没有它，守护进程拒绝远程端点，因此输入错误的URL永远不会将内存文本发送到框外（保护嵌入提供者和重新排序者）。 |
| `BASTRA_OLLAMA_KEEP_ALIVE` | 否 | `10m` | 每个请求 `keep_alive` 窗口-每次嵌入后，Ollama在RAM中保留嵌入模型的时间 |
| `BASTRA_OLLAMA_IDLE_UNLOAD_MS` | 否 | `600000` (10分钟) | 在很长一段时间没有嵌入后，从Ollama RAM中卸载嵌入模型（节省电池）； `0` 禁用 |
| `BASTRA_BATTERY_SAVER` | 否 | 设置(→ `battery.saver`，默认关闭) | macOS上的电池模式（#632）： `1` / `0` 覆盖设置文件。在电池上，doc2query等待交流，预热被跳过，空闲卸载在60秒后触发 [用法](https://npmcn.com/package/docs/USAGE.md) |
| `OPENAI_API_KEY` | 否 | 设置 | 时需要 `BASTRA_EMBEDDING_PROVIDER=openai` |
| `BASTRA_FORWARDER_SPAWN` | 否 | `1` | 当 `0`， MCP转发器将不会自动生成守护进程。这仍然是仅服务启动的解决方案，使用 `BASTRA_DAEMON_URL` 命名那个所有者。macOS托管服务现在自动获得10秒的机会；转发器后面的无头服务等待其空闲退出（#758）。Linux托管安装紧随#566 |
| `BASTRA_DAEMON_URL` | 否 | `http://127.0.0.1:6723` | 这台机器指的是哪个守护进程—自#531以来每个表面使用的单端点解析器的最高优先级输入（CLI、doctor、map、hooks、转送程序、桥接程序和守护进程自己的绑定），以及什么 `bastra install` 写入客户端注册 |
| `BASTRA_HOOK_TIMEOUT_MS` | 否 | 每道 | 在故障静默之前覆盖车道的挂钟预算-每个车道的默认值都在 [文档/ hooks.md](https://npmcn.com/package/docs/hooks.md#budgets-and-the-release-threshold-305) (# 305) |
| `BASTRA_VECTOR_DEADLINE_MS` | 否 | `150` | 仅钩路径：在仅服务bm25之前，召回等待密集臂的时间。这个阶段，而不是呼叫的范围——测量手臂的温暖花费了87-96ms（总共106-113ms），寒冷花费了668ms（总共694ms），所以每个温暖的呼叫花费了150ms，而寒冷的呼叫在180ms左右结束。嵌入被放弃，而不是取消，所以模型仍然完成加载，下一个调用是热的。退化可见为 `degraded: "vector-arm-timeout"`； `0` 禁用（终止开关） |
| `BASTRA_HOOK_MAX_SHOW` | 否 | `1` | 同样的记忆在大脑中出现的频率是多少 `<recall-hints>` 每个会话（4小时窗口）；一个 `load_memory` 的id重置计数器 |
| `BASTRA_HOOK_CONTENT_RECALL` | 否 | `off` | 设置为 `1` 运行可选编辑-内容召回臂（#282） |
| `BASTRA_DOCUMENT_WRITE` | 否 | 设置 | 设置为 `1` 公开文档编写工具 |
| `BASTRA_LOG_PATH` | 否 | `~/.bastra/logs` | 遥测JSONL输出目录（故意出库） |
| `BASTRA_TELEMETRY` | 否 | `on` | 设置为 `off` 完全禁用遥测写入 |

## 遥测

每一个 `recall`， `load_memory`， `save_memory` 和钩子调用追加一个JSON行到 `events-YYYY-MM-DD.jsonl` 在日志目录中。每个守护进程获得一个fresh `session_id`;召回 `recall_id` 和任何 `load_memory` / `save_memory` 在5分钟内引用id为 `follows_recall`.

这足以计算：

-   每个会话的回收次数，命中次数，得分分布，延迟p50/p95
-   Recall→load\_memory后续通过率（代表“提示有用吗？”）
-   每个会话保存，类型/作用域分布，% overwrite vs. new
-   保存→跟踪召回率（重复检查完成了吗？）
-   每钩子延迟和命中质量（在哪里PreToolUse / SessionStart实际上有帮助？）

日志存在于保险库之外，因此文件监视程序不会对它们进行索引。观看直播的尾巴： `tail -f ~/.bastra/logs/events-$(date +%F).jsonl`.

## 搜索排名

磁场增强(在 `src/search.ts`):

```
recall_when_flat:          5    ← authored for triggering, highest weight
title:                     4
tags_flat:                 3
recall_when_expanded_flat: 2    ← doc2query paraphrases (#117): machine-generated, below the author's words
topic_path_flat:           2
summary:                   2
body:                      1
```

模糊距离0.2，启用前缀匹配； `combineWith: "OR"`． 混合模式通过倒数秩融合（RRF）将BM25与嵌入余弦结合起来；每次召回时，嵌入查询将转到提供者一次，并缓存在内存中。

## 模式参考

看到 [`../../docs/memory-schema.md`](https://npmcn.com/package/docs/memory-schema.md) 对于全内存前端事务规范，守护进程通过 [`zod`](https://zod.dev/) 加载时，将跳过验证失败的文件，并发出错误警告。

## 限制

-   **共享的过程。** 转发器根据需要启动守护进程。在macOS, `bastra autostart on` 管理一个可选的LaunchAgent来保持它的运行；使用 `bastra autostart off` 回到按需操作。
-   **云存储挂载** （谷歌驱动器，iCloud, Dropbox）需要轮询模式在chokidar -默认启用，但手表延迟可能是几秒钟。
-   **游标规则是针对每个项目的。** `bastra install cursor` 寄存器MCP。运行 `bastra rules cursor` 在每个项目内部安装共享内存指南。

## 常见问题

### @bastra-recall/daemon 是什么？

MCP服务器在markdown vault上：recall， load\_memory, save\_memory, edit\_memory， archive\_memory和文档工具-加上REST网关，安静的钩子通道和基础命令行。

### 如何安装 @bastra-recall/daemon？

在项目目录运行 npm install @bastra-recall/daemon，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 bastra、bastra-recall-mcp、bastra-recall-hook、bastra-recall-bridge、bastra-recall-daemon、bastra-recall-gate-hook、bastra-recall-stop-hook、bastra-recall-todo-hook、bastra-recall-prompt-hook、bastra-recall-session-hook、bastra-recall-bash-pre-hook、bastra-recall-bash-fail-hook，可以用 npx bastra 直接运行。

### @bastra-recall/daemon 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/bastra-recall\_\_daemon 是否存在。

### @bastra-recall/daemon 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @bastra-recall/daemon 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @bastra-recall/daemon 可以商用吗？

@bastra-recall/daemon 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @bastra-recall/daemon 还在维护吗？

最新版本 1\.1\.8 发布于 2026/10/31（2 天前）；至今共发布 27 个版本，其中过去 12 个月发布了 27 个；首次发布于 2026/06/23。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。