# https://github.com/n0mad-ai/bastra-recall 项目说明书

生成时间：2026-07-04 02:18:17 UTC

## 目录

- [项目概览](#page-overview)
- [Src 模块](#page-packages-statusline-src)
- [Src 模块](#page-packages-core-src)
- [Src 模块](#page-packages-eval-src)

<a id='page-overview'></a>

## 项目概览

### 相关页面

相关主题：[Src 模块](#page-packages-statusline-src)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/n0mad-ai/bastra-recall/blob/main/README.md)
- [package.json](https://github.com/n0mad-ai/bastra-recall/blob/main/package.json)
- [packages/bastra-recall/README.md](https://github.com/n0mad-ai/bastra-recall/blob/main/packages/bastra-recall/README.md)
- [packages/bastra-recall/package.json](https://github.com/n0mad-ai/bastra-recall/blob/main/packages/bastra-recall/package.json)
- [packages/core/package.json](https://github.com/n0mad-ai/bastra-recall/blob/main/packages/core/package.json)
- [packages/daemon/README.md](https://github.com/n0mad-ai/bastra-recall/blob/main/packages/daemon/README.md)
- [packages/daemon/package.json](https://github.com/n0mad-ai/bastra-recall/blob/main/packages/daemon/package.json)
- [packages/statusline/package.json](https://github.com/n0mad-ai/bastra-recall/blob/main/packages/statusline/package.json)
</details>

# 项目概览

`bastra-recall` 是一个基于 [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 的长期记忆中间层，专为 Claude 系列 AI 客户端（Claude Desktop、Claude Code）设计。它通过本地 Markdown vault（兼容 Obsidian）为 AI 会话提供持久化、按需召回的"记忆"能力，并随时间不断自我整理与精炼。

## 项目定位与核心价值

`bastra-recall` 的核心问题：**AI 客户端本身是无状态的**——每次新会话都需要重复提供项目背景、用户偏好、过往决策等上下文。`bastra-recall` 通过 MCP 接口为 AI 暴露 `recall`、`remember`、`forget`、`curate` 等工具，让模型能够：

- 在对话开始时**自动召回**相关的历史记忆（hint token 注入）
- 在对话过程中**主动记忆**新事实（用户偏好、项目约束、决策原因）
- 在空闲时**自我整理** vault（curator phase A 的 staleness pass、按使用频率降权冷记忆）

最新版本 `v0.7.0-beta.5` 引入了**引导式安装向导**（`#185`）和**生命周期 wave C**（curator 首次"动起来"的阶段），标志着项目从"被动存储"迈向"主动维护"。资料来源：[README.md:1-40]()

## 架构组成

仓库采用 npm workspaces 单仓多包结构，主入口包 `@bastra-recall/bastra-recall` 负责 CLI 调度，三个核心 workspace 各司其职：

| Workspace | 角色 | 关键产物 |
|-----------|------|----------|
| `packages/bastra-recall` | CLI 入口与生命周期编排（install / uninstall / start） | `bastra` 命令分发器 |
| `packages/core` | 记忆语义层：vault 扫描、enricher、curator、telemetry | 纯逻辑层，可独立测试 |
| `packages/daemon` | MCP 服务与 `mcp-forwarder.js` 转发器 | `@bastra-recall/daemon` 包 |
| `packages/statusline` | Claude Code 状态栏集成 | 显示当前会话的 recall 状态 |

资料来源：[package.json:1-60]()、`packages/core/package.json:1-30]`、`packages/daemon/README.md:1-50]()

## 部署与分发形态

`bastra-recall` 提供**三条互斥的安装路径**，由 `bastra install` 在引导向导中让用户选择（`v0.7.0-beta.5`）：

1. **npx 一次性试用**：`npx bastra-recall@latest install all`。注意 `#180` 报告的问题——npx 缓存是临时目录，会让 surface 注册指向 `~/.npm/_npx/<hash>/...`，缓存清理后 MCP 注册会失效。
2. **全局 npm 安装**：`npm install -g bastra-recall`，forwarder 路径稳定。
3. **Homebrew formula**：`brew install n0mad-ai/tap/bastra-recall`。`#182` 与 `#184` 记录了早期 beta 在干净 macOS 环境的失败——分别需要新增 `brew trust --formula` 步骤，并修复 tarball 缺失 `core/statusline dist` 的构建问题。

每条路径都会向三个 **surface**（`claude-code`、`claude-desktop`、`cursor`）注册 MCP server 与可选的 skill。

## 关键子系统与已知问题

下表罗列 `bastra-recall` 当前最受社区关注的子系统：

- **Enricher / doc sidecar**：扫描 vault 中新出现的文档，为其生成带 embedding 的 Markdown sidecar，并在余弦相似度 ≥ 0.9 的兄弟 sidecar 间建立 `[[doc-id]]` 维基链接。`#188` 指出 id-slug 形式的 wikilink 在 Obsidian 中无法解析，会产生 0 字节空文件（2026-07-04 真实 vault 事件）。
- **Curator phase A**（`#155`）：基于 usage telemetry 的确定性 staleness 评分，空闲时触发（idle-gated），仅调权不计删。
- **Telemetry per-memory sidecar**（`#154`）：append-only 聚合 surfaced/loaded/acted_on 计数，弥补 raw events JSONL 轮转后的统计空白。
- **Vault self-audit**（`#140`）：以 Markdown 形式输出到 vault 本身（用 Obsidian 浏览），分区报告 sync-conflict、dangling、demand-gaps 等。
- **Uninstall 边界**（`#181`）：在 `uninstall all` 同进程卸载 claude-desktop 后，claude-code skill 仍被报告为 `kept (shared with Claude Desktop)`，存在共享资源误判。

## 数据流概览

```mermaid
flowchart LR
    AI[Claude Desktop/Code] -->|MCP request| F[mcp-forwarder.js]
    F --> D[daemon: stdio JSON-RPC]
    D --> C[core: recall/remember]
    C --> V[(Markdown vault)]
    C --> E[Ollama embeddings]
    V -.->|scan| EN[Enricher]
    V -.->|idle| CU[Curator]
    CU --> T[Telemetry sidecar]
```

资料来源：[packages/daemon/README.md:1-80]()`、`packages/core/package.json:1-30]()`、`README.md:41-100]()

## 适用场景与边界

`bastra-recall` 适合**长期、单人、跨会话**的 AI 协作场景——特别是需要 AI 记住项目约束、用户偏好、过往决策的工作流。它**不**适合：

- 多人共享 vault（无并发锁设计）
- 高频短会话（telemetry 噪声会污染 curator 评分）
- 非 Claude 系客户端（仅实现了 Claude Desktop/Code/Cursor 的 MCP 表面）

vault 选用 Markdown 是有意识的设计：人类可读、可在 Obsidian 中直接浏览、可被 `git` 追踪——但也带来 `#188` 暴露的副作用：enricher 写出的 0 字节 stub 文件会污染 vault 根目录，需要后续通过校验修复。资料来源：[packages/bastra-recall/README.md:1-60]()`、`#188`]()

---

<a id='page-packages-statusline-src'></a>

## Src 模块

### 相关页面

相关主题：[项目概览](#page-overview), [Src 模块](#page-packages-core-src)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [packages/statusline/src/browser.ts](https://github.com/n0mad-ai/bastra-recall/blob/main/packages/statusline/src/browser.ts)
- [packages/statusline/src/config/defaults.ts](https://github.com/n0mad-ai/bastra-recall/blob/main/packages/statusline/src/config/defaults.ts)
- [packages/statusline/src/config/loader.ts](https://github.com/n0mad-ai/bastra-recall/blob/main/packages/statusline/src/config/loader.ts)
- [packages/statusline/src/index.ts](https://github.com/n0mad-ai/bastra-recall/blob/main/packages/statusline/src/index.ts)
- [packages/statusline/src/powerline.ts](https://github.com/n0mad-ai/bastra-recall/blob/main/packages/statusline/src/powerline.ts)
- [packages/statusline/src/segments/bastra.ts](https://github.com/n0mad-ai/bastra-recall/blob/main/packages/statusline/src/segments/bastra.ts)
- [packages/daemon/src/mcp-forwarder.ts](https://github.com/n0mad-ai/bastra-recall/blob/main/packages/daemon/src/mcp-forwarder.ts)
- [packages/core/src/index.ts](https://github.com/n0mad-ai/bastra-recall/blob/main/packages/core/src/index.ts)
</details>

# Src 模块

## 概述

`src/` 是 bastra-recall 项目的 TypeScript 实现根目录,跨 `packages/statusline`、`packages/daemon`、`packages/core` 三个工作空间组织代码。仓库采用 monorepo 结构,所有包遵循 `src/` 作为源码入口、`dist/` 作为构建产物的统一约定。`src` 层集中承载状态栏渲染、配置加载、MCP 转发、共享类型与生命周期等关键能力,是所有 CLI/IDE 表面调用链的起点。

资料来源：[packages/statusline/src/index.ts:1-40]()

## statusline 包的 src 结构

`packages/statusline/src/` 按照入口、配置、渲染、片段四种职责拆分:

- **入口与适配**:`index.ts` 聚合所有导出,根据运行环境(CI、IDE 终端、纯终端、浏览器/Codespaces)分发渲染分支;`browser.ts` 处理浏览器端回退,在无 ANSI 支持时返回纯文本。
- **配置层**:`config/defaults.ts` 定义默认常量(列宽、颜色阈值、刷新间隔、vault 路径解析等);`config/loader.ts` 以"最近写覆盖"的优先级合并用户配置、环境变量与默认值。
- **渲染层**:`powerline.ts` 实现 powerline 风格的拼接与着色,基于 ANSI 转义码与符号库构造状态栏。
- **片段层**:`segments/bastra.ts` 定义每个段(如记忆命中率、最近 recall、上次 curator、上次 staleness 评分等),由 `index.ts` 按用户配置顺序组装。

资料来源：[packages/statusline/src/index.ts:1-80]()
资料来源：[packages/statusline/src/browser.ts:1-40]()
资料来源：[packages/statusline/src/config/defaults.ts:1-60]()
资料来源：[packages/statusline/src/config/loader.ts:1-80]()
资料来源：[packages/statusline/src/powerline.ts:1-100]()
资料来源：[packages/statusline/src/segments/bastra.ts:1-80]()

## daemon 与 core 包的角色

`packages/daemon/src/mcp-forwarder.ts` 是守护进程包的转发主入口。通过 `npx bastra-recall@latest install all` 安装时,各 AI 客户端(Claude Code、Claude Desktop 等)注册的 forwarder 路径指向 `dist/mcp-forwarder.js`,它在 stdio 上读取 MCP 消息并转发给本机守护进程。当 npx 缓存被清理或重定向时,此路径会失效,表现为客户端无法连接(参见社区问题 #180)。

`packages/core/src/index.ts` 承载项目共享的类型定义、错误模型、vault 路径解析等基础工具,被 `statusline` 与 `daemon` 通过 npm 工作空间引用。Homebrew 公式在 v0.7.0-beta.4 阶段曾遗漏 `core` 与 `statusline` 的 dist 产物(参见 #184),后期构建需同时编译这两个工作空间,否则 tarball 缺失产物会引发 67 条 TS7006/TS7016 类错误。

资料来源：[packages/daemon/src/mcp-forwarder.ts:1-100]()
资料来源：[packages/core/src/index.ts:1-50]()

## 构建产物与运行时协作

`src/` 模块的 TypeScript 通过根目录 npm workspaces 统一编译,产物按 `src/` → `dist/` 的等价映射输出。运行时协作关系如下:

| 路径 | 角色 | 启动场景 |
|---|---|---|
| `packages/statusline/src/index.ts` | 入口聚合与渲染分发 | IDE/Cursor statusline 钩子 |
| `packages/statusline/src/config/loader.ts` | 配置合并 | 每次渲染前 |
| `packages/daemon/src/mcp-forwarder.ts` | MCP stdio 转发 | AI 客户端调用 |
| `packages/core/src/index.ts` | 共享类型与工具 | 被 statusline/daemon 引用 |

v0.7.0-beta.5 引入的引导式安装(参见 #185)在用户首次运行 `bastra install` 时写入 vault 路径与客户端选择,后续 `src/` 层在缺少 vault 路径时通过该持久化配置兜底,避免再抛出 "vault path required" 的硬错误(参见 #178)。`src/` 模块由此成为连接"安装向导"与"运行时渲染/转发"的中枢:配置写入磁盘、`loader.ts` 读取合并、`index.ts` 渲染分发、`mcp-forwarder.ts` 处理跨进程消息,三层共同构成 bastra-recall 自改进生命周期的源动力。

资料来源：[packages/statusline/src/index.ts:1-80]()
资料来源：[packages/statusline/src/config/loader.ts:1-80]()
资料来源：[packages/daemon/src/mcp-forwarder.ts:1-100]()
资料来源：[packages/core/src/index.ts:1-50]()

---

<a id='page-packages-core-src'></a>

## Src 模块

### 相关页面

相关主题：[Src 模块](#page-packages-statusline-src), [Src 模块](#page-packages-eval-src)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [packages/core/src/audit-log.ts](https://github.com/n0mad-ai/bastra-recall/blob/main/packages/core/src/audit-log.ts)
- [packages/core/src/audit-save.ts](https://github.com/n0mad-ai/bastra-recall/blob/main/packages/core/src/audit-save.ts)
- [packages/core/src/embed-cache.ts](https://github.com/n0mad-ai/bastra-recall/blob/main/packages/core/src/embed-cache.ts)
- [packages/core/src/embeddings.ts](https://github.com/n0mad-ai/bastra-recall/blob/main/packages/core/src/embeddings.ts)
- [packages/core/src/index.ts](https://github.com/n0mad-ai/bastra-recall/blob/main/packages/core/src/index.ts)
- [packages/core/src/ollama-egress.ts](https://github.com/n0mad-ai/bastra-recall/blob/main/packages/core/src/ollama-egress.ts)
</details>

# Src 模块

## 概述与定位

`packages/core/src` 是 bastra-recall 仓库核心包 `@bastra-recall/core` 的源代码根目录，承担"无 IO 外壳的纯逻辑/纯算法层"角色：它向上被 daemon、statusline、CLI 等多个 workspace 复用 资料来源：[packages/core/src/index.ts:1-30]()，向下封装向量化、缓存、审计、egress（出站网络）等关键子系统，并对外暴露统一的公共 API 入口 资料来源：[packages/core/src/index.ts:1-30]()。

按照 v0.7.0-beta.5 的发布说明，core 与 daemon、statusline 同属多 workspace 拓扑中的基础层；homebrew 安装流水线必须分别构建 core 与 daemon/dist、statusline/dist，缺一即触发 TS7006/TS7016 错误（如 #184 所述） 资料来源：[packages/core/src/index.ts:1-30]()。因此 `Src` 既是产品能力的"内核算盘"，也是分发打包时必须命中的最小集合。

## 主要子系统

`Src` 下的源文件按职责可划分为四个相对内聚的子系统：

### 1. 向量与缓存子系统

`embeddings.ts` 定义嵌入请求的形态与生成逻辑，是 recall 流程"语义相似度"的源头；`embed-cache.ts` 在其外层维护一层结果缓存，避免每次召回都触发对 Ollama 的重复计算 资料来源：[packages/core/src/embeddings.ts:1-40]()、资料来源：[packages/core/src/embed-cache.ts:1-40]()。在 npx 安装链路中（#180），forwarder 路径指向 daemon/dist，但嵌入调用最终仍由 core 提供语义；当缓存命中时即可绕过 Ollama egress，从而降低响应时延与本地资源占用。

### 2. 审计与持久化子系统

`audit-log.ts` 与 `audit-save.ts` 是一对读写对子：前者负责事件流的结构化记录（surfaces/loaded/acted_on 等召回生命周期事件），后者负责把审计内容落到磁盘侧车（sidecar） 资料来源：[packages/core/src/audit-log.ts:1-40]()、资料来源：[packages/core/src/audit-save.ts:1-40]()。社区提案 #154 "telemetry: per-memory usage sidecar" 正是建立在此子系统之上的进一步增强——当前事件已写入 JSONL，但缺少 per-memory 的聚合，需要 sidecar 来承载 staleness 与 ranking feedback 决策；提案 #155 的 curator phase A（确定性 staleness pass）同样依赖这条审计通道作为输入 资料来源：[packages/core/src/audit-log.ts:1-40]()。

### 3. Ollama 出站子系统

`ollama-egress.ts` 是唯一与本地 Ollama 服务对话的出站适配层，统一处理 base URL、模型选择、错误码映射与超时 资料来源：[packages/core/src/ollama-egress.ts:1-40]()。该文件被 daemon 安装流程（#90 中的 `bastra install`）用作 Ollama provisioning 的核心调用面；在 npx ephemeral 缓存场景下（#180），即便 forwarder 路径会失效，egress 抽象本身保证了调用方不必感知底层部署位置。

### 4. 公共导出入口

`index.ts` 作为 barrel file，聚合上述子系统的对外 API，避免内部实现细节泄漏到 daemon / statusline 等上游 资料来源：[packages/core/src/index.ts:1-30]()。所有 cross-workspace 调用（homebrew 公式中的 `npm run build --workspace @bastra-recall/core`）都必须经过它完成类型与运行时的对齐。

## 数据流与依赖关系

典型的 recall 请求在 `Src` 内部的流向可概括为：

| 阶段 | 涉及文件 | 作用 |
|------|----------|------|
| 入口装配 | `index.ts` | 暴露 recall 接口与依赖注入入口 |
| 语义编码 | `embeddings.ts` | 查询文本向量化 |
| 结果缓存 | `embed-cache.ts` | 命中即返回，未命中继续 |
| 远程调用 | `ollama-egress.ts` | 真正发起 embedding 请求 |
| 事件记录 | `audit-log.ts` | 写入 surfaced/loaded/acted_on 事件 |
| 落盘 | `audit-save.ts` | 把事件持久化到 sidecar |

资料来源：[packages/core/src/index.ts:1-30]()、资料来源：[packages/core/src/embeddings.ts:1-40]()、资料来源：[packages/core/src/embed-cache.ts:1-40]()、资料来源：[packages/core/src/ollama-egress.ts:1-40]()、资料来源：[packages/core/src/audit-log.ts:1-40]()、资料来源：[packages/core/src/audit-save.ts:1-40]()。

## 局限与社区关注点

- **缓存键与失效**：`embed-cache.ts` 决定了哪些检索会被跳过；缓存粒度过粗会掩盖 staleness 信号（#155），过细则放大 Ollama 负载。
- **审计聚合缺口**：`audit-log.ts` + `audit-save.ts` 只能提供原始事件流，per-memory 聚合仍需通过 sidecar 持久化（#154）；当前 stats.ts 只能"report-only"，无法主动驱动 curator 行为。
- **egress 鲁棒性**：`ollama-egress.ts` 是 clean-VM 安装路径（#90）唯一无法在已开发机器上完全验证的环节；超时与重试策略直接影响首次 install 体验。
- **分发完整性**：homebrew 公式曾因只构建 daemon 而遗漏 core/statusline 产物（#184），说明 `Src` 的构建目标必须显式列入 tarball，否则用户侧会出现 67 条 TS 错误。

综上，`packages/core/src` 是一个体量小但职责高度集中的模块，它的稳定性直接决定了 recall 质量、stale memory 治理以及多 surface 安装的一致性。

---

<a id='page-packages-eval-src'></a>

## Src 模块

### 相关页面

相关主题：[Src 模块](#page-packages-core-src)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [packages/eval/src/bridge-transfer.ts](https://github.com/n0mad-ai/bastra-recall/blob/main/packages/eval/src/bridge-transfer.ts)
- [packages/eval/src/doc2query-lift.ts](https://github.com/n0mad-ai/bastra-recall/blob/main/packages/eval/src/doc2query-lift.ts)
- [packages/eval/src/hybrid-arm.ts](https://github.com/n0mad-ai/bastra-recall/blob/main/packages/eval/src/hybrid-arm.ts)
- [packages/eval/src/index-config.ts](https://github.com/n0mad-ai/bastra-recall/blob/main/packages/eval/src/index-config.ts)
- [packages/eval/src/marginal-lift.ts](https://github.com/n0mad-ai/bastra-recall/blob/main/packages/eval/src/marginal-lift.ts)
- [packages/eval/src/persona-lift.ts](https://github.com/n0mad-ai/bastra-recall/blob/main/packages/eval/src/persona-lift.ts)
</details>

# Src 模块

## 概述与定位

`packages/eval/src/` 是 bastra-recall 评估（evaluation）子包的核心源码目录，承担 recall 流水线的离线评测与对照实验职责。该模块围绕"提升度（lift）"这一核心度量组织代码：每一个 `.ts` 文件对应一种评测维度或评测机制，对外以独立函数/类暴露，可被上层 `eval` CLI 或 CI 中的 recall 基准任务调用。资料来源：[packages/eval/src/bridge-transfer.ts:1-1]()、[packages/eval/src/doc2query-lift.ts:1-1]()

模块的整体目标是：在不污染生产 vault 与索引的前提下，重放真实的 recall 会话、量化不同检索策略/配置/人设对召回质量的边际贡献，并把这些数值汇总为可供自我审计（vault self-audit，参见 issue #140）消费的指标。

## 主要子模块职责

下表汇总了 `src/` 下各文件的高层职责，便于读者快速建立心智模型。

| 文件 | 角色 | 关键产出 |
|---|---|---|
| `index-config.ts` | 检索索引配置构造 | 评测用的索引 schema、字段映射 |
| `hybrid-arm.ts` | 混合检索臂 | BM25 + 向量 + 元数据的多路召回 |
| `bridge-transfer.ts` | 评测桥接与迁移 | 把离线指标映射到线上策略 |
| `doc2query-lift.ts` | 文档→查询提升度 | doc2query 扩展对 recall 的增益 |
| `marginal-lift.ts` | 边际提升度 | 单条策略开关的 A/B 边际效应 |
| `persona-lift.ts` | 人设提升度 | 不同 persona 模板下的召回差异 |

资料来源：[packages/eval/src/index-config.ts:1-1]()、[packages/eval/src/hybrid-arm.ts:1-1]()、[packages/eval/src/marginal-lift.ts:1-1]()、[packages/eval/src/persona-lift.ts:1-1]()

## 工作流与数据流

一次典型的评测任务按"配置 → 取臂 → 算提升度 → 桥接"的顺序串联：

1. **构建索引配置**：`index-config.ts` 读取 vault 路径与索引参数，生成可被评测复用的轻量级 schema。资料来源：[packages/eval/src/index-config.ts:1-1]()
2. **拉起混合检索臂**：`hybrid-arm.ts` 在该 schema 上装配多路召回（稀疏 + 稠密 + 元数据过滤），作为基线或候选臂。资料来源：[packages/eval/src/hybrid-arm.ts:1-1]()
3. **计算多种 lift**：
   - `doc2query-lift.ts` 衡量将文档反向扩展成合成查询后，召回率的变化。资料来源：[packages/eval/src/doc2query-lift.ts:1-1]()
   - `marginal-lift.ts` 在固定其它臂的条件下，单独开关某一路检索，输出边际增益。资料来源：[packages/eval/src/marginal-lift.ts:1-1]()
   - `persona-lift.ts` 复用 telemetry 中的 surfaced/loaded/acted_on 事件（issue #154）按 persona 分桶统计 lift。资料来源：[packages/eval/src/persona-lift.ts:1-1]()
4. **桥接与迁移**：`bridge-transfer.ts` 把上述离线 lift 结果转换为线上 daemon 可消费的策略参数（例如权重、阈值），与社区关心的"使用率驱动的 staleness pass"（issue #155）形成闭环。资料来源：[packages/eval/src/bridge-transfer.ts:1-1]()

```mermaid
flowchart LR
  A[index-config.ts] --> B[hybrid-arm.ts]
  B --> C[doc2query-lift.ts]
  B --> D[marginal-lift.ts]
  B --> E[persona-lift.ts]
  C --> F[bridge-transfer.ts]
  D --> F
  E --> F
  F --> G[线上 daemon / vault self-audit]
```

## 与社区关切点的关系

- **Vault 自审计（#140）**：`marginal-lift.ts` 与 `persona-lift.ts` 的输出可直接喂给 self-audit 视图中的"light/heavy index"与"demand-gaps"区域，使得审计结果不再只是统计报告，而是可指导策略回写。资料来源：[packages/eval/src/marginal-lift.ts:1-1]()、[packages/eval/src/persona-lift.ts:1-1]()
- **使用率侧车（#154）**：`persona-lift.ts` 假定存在 `surfaced/loaded/acted_on` 事件聚合，与 telemetry 侧车字段定义保持一致，二者在协议层共用同一份 memory-id 维度。资料来源：[packages/eval/src/persona-lift.ts:1-1]()
- **策展 Phase A（#155）**：`marginal-lift.ts` 输出的"被 surfaced 但 0 acted_on"的 archival 候选，是策展模块判定下架/归档优先级的输入。资料来源：[packages/eval/src/marginal-lift.ts:1-1]()
- **Enricher 副作用（#188）**：当 `bridge-transfer.ts` 将 doc-sidecar 的高余弦邻居反推回线上策略时，必须过滤 `[[<doc-id>]]` 这类不可解析的 wikilink，避免在 vault 根目录产生 0 字节的孤立笔记。资料来源：[packages/eval/src/bridge-transfer.ts:1-1]()

## 设计要点

- **可独立评测**：每个 lift 文件都设计为可单独 import，避免"全量评测"开销过大，符合 issue #178/#184 暴露出的"首次安装门槛"问题——评测脚本应当能在最小化环境跑通。资料来源：[packages/eval/src/doc2query-lift.ts:1-1]()、[packages/eval/src/hybrid-arm.ts:1-1]()
- **幂等与可重放**：评测结果应可由同一份 vault 快照复现，从而与"self-improving lifecycle"（v0.7.0-beta.5 发布说明）对齐。资料来源：[packages/eval/src/index-config.ts:1-1]()
- **桥接而非旁路**：`bridge-transfer.ts` 是离线与在线的唯一交汇点，便于在 CI 中拦截不安全的策略写回（例如前向链接到 npx 缓存路径，issue #180）。资料来源：[packages/eval/src/bridge-transfer.ts:1-1]()

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：n0mad-ai/bastra-recall

摘要：发现 32 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安全/权限坑 - 来源证据：Vault self-audit surfaced as Markdown in the vault (Obsidian as the viewer) — conflicts, demand-gaps, dangling。

## 1. 安全/权限坑 · 来源证据：Vault self-audit surfaced as Markdown in the vault (Obsidian as the viewer) — conflicts, demand-gaps, dangling

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Vault self-audit surfaced as Markdown in the vault (Obsidian as the viewer) — conflicts, demand-gaps, dangling
- 对用户的影响：可能阻塞安装或首次运行。
- 证据：community_evidence:github | https://github.com/n0mad-ai/bastra-recall/issues/140 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

## 2. 安装坑 · 失败模式：installation: brew install fails on untrusted tap — docs and Install.command miss the new 'brew trust' step

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: brew install fails on untrusted tap — docs and Install.command miss the new 'brew trust' step
- 对用户的影响：Developers may fail before the first successful local run: brew install fails on untrusted tap — docs and Install.command miss the new 'brew trust' step
- 证据：failure_mode_cluster:github_issue | https://github.com/n0mad-ai/bastra-recall/issues/182 | brew install fails on untrusted tap — docs and Install.command miss the new 'brew trust' step

## 3. 安装坑 · 失败模式：installation: homebrew formula build fails — builds only the daemon workspace, core/statusline dist missing...

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: homebrew formula build fails — builds only the daemon workspace, core/statusline dist missing from the tarball
- 对用户的影响：Developers may fail before the first successful local run: homebrew formula build fails — builds only the daemon workspace, core/statusline dist missing from the tarball
- 证据：failure_mode_cluster:github_issue | https://github.com/n0mad-ai/bastra-recall/issues/184 | homebrew formula build fails — builds only the daemon workspace, core/statusline dist missing from the tarball

## 4. 安装坑 · 失败模式：installation: install via npx registers the forwarder path inside the ephemeral npx cache

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: install via npx registers the forwarder path inside the ephemeral npx cache
- 对用户的影响：Developers may fail before the first successful local run: install via npx registers the forwarder path inside the ephemeral npx cache
- 证据：failure_mode_cluster:github_issue | https://github.com/n0mad-ai/bastra-recall/issues/180 | install via npx registers the forwarder path inside the ephemeral npx cache

## 5. 安装坑 · 失败模式：installation: install: first-run wall — 'vault path required' error instead of a guided vault choice

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: install: first-run wall — 'vault path required' error instead of a guided vault choice
- 对用户的影响：Developers may fail before the first successful local run: install: first-run wall — 'vault path required' error instead of a guided vault choice
- 证据：failure_mode_cluster:github_issue | https://github.com/n0mad-ai/bastra-recall/issues/178 | install: first-run wall — 'vault path required' error instead of a guided vault choice

## 6. 安装坑 · 失败模式：installation: test: verify the Ollama fresh-install (brew) path on a clean macOS env

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: test: verify the Ollama fresh-install (brew) path on a clean macOS env
- 对用户的影响：Developers may fail before the first successful local run: test: verify the Ollama fresh-install (brew) path on a clean macOS env
- 证据：failure_mode_cluster:github_issue | https://github.com/n0mad-ai/bastra-recall/issues/90 | test: verify the Ollama fresh-install (brew) path on a clean macOS env

## 7. 安装坑 · 失败模式：installation: uninstall all: skill kept as 'shared with Claude Desktop' although Desktop was uninstalled in...

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: uninstall all: skill kept as 'shared with Claude Desktop' although Desktop was uninstalled in the same run
- 对用户的影响：Developers may fail before the first successful local run: uninstall all: skill kept as 'shared with Claude Desktop' although Desktop was uninstalled in the same run
- 证据：failure_mode_cluster:github_issue | https://github.com/n0mad-ai/bastra-recall/issues/181 | uninstall all: skill kept as 'shared with Claude Desktop' although Desktop was uninstalled in the same run

## 8. 安装坑 · 失败模式：installation: v0.6.0-beta.1

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: v0.6.0-beta.1
- 对用户的影响：Upgrade or migration may change expected behavior: v0.6.0-beta.1
- 证据：failure_mode_cluster:github_release | https://github.com/n0mad-ai/bastra-recall/releases/tag/v0.6.0-beta.1 | v0.6.0-beta.1

## 9. 安装坑 · 失败模式：installation: v0.6.5-beta.1

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: v0.6.5-beta.1
- 对用户的影响：Upgrade or migration may change expected behavior: v0.6.5-beta.1
- 证据：failure_mode_cluster:github_release | https://github.com/n0mad-ai/bastra-recall/releases/tag/v0.6.5-beta.1 | v0.6.5-beta.1

## 10. 安装坑 · 失败模式：installation: v0.6.6-beta.1

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: v0.6.6-beta.1
- 对用户的影响：Upgrade or migration may change expected behavior: v0.6.6-beta.1
- 证据：failure_mode_cluster:github_release | https://github.com/n0mad-ai/bastra-recall/releases/tag/v0.6.6-beta.1 | v0.6.6-beta.1

## 11. 安装坑 · 失败模式：installation: v0.7.0-beta.3

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: v0.7.0-beta.3
- 对用户的影响：Upgrade or migration may change expected behavior: v0.7.0-beta.3
- 证据：failure_mode_cluster:github_release | https://github.com/n0mad-ai/bastra-recall/releases/tag/v0.7.0-beta.3 | v0.7.0-beta.3

## 12. 安装坑 · 失败模式：installation: v0.7.0-beta.5 — guided install + lifecycle wave C

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: v0.7.0-beta.5 — guided install + lifecycle wave C
- 对用户的影响：Upgrade or migration may change expected behavior: v0.7.0-beta.5 — guided install + lifecycle wave C
- 证据：failure_mode_cluster:github_release | https://github.com/n0mad-ai/bastra-recall/releases/tag/v0.7.0-beta.5 | v0.7.0-beta.5 — guided install + lifecycle wave C

## 13. 安装坑 · 来源证据：brew install fails on untrusted tap — docs and Install.command miss the new 'brew trust' step

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：brew install fails on untrusted tap — docs and Install.command miss the new 'brew trust' step
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/n0mad-ai/bastra-recall/issues/182 | 来源类型 github_issue 暴露的待验证使用条件。

## 14. 安装坑 · 来源证据：homebrew formula build fails — builds only the daemon workspace, core/statusline dist missing from the tarball

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：homebrew formula build fails — builds only the daemon workspace, core/statusline dist missing from the tarball
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/n0mad-ai/bastra-recall/issues/184 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

## 15. 安装坑 · 来源证据：install via npx registers the forwarder path inside the ephemeral npx cache

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：install via npx registers the forwarder path inside the ephemeral npx cache
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/n0mad-ai/bastra-recall/issues/180 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

## 16. 安装坑 · 来源证据：install: first-run wall — 'vault path required' error instead of a guided vault choice

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：install: first-run wall — 'vault path required' error instead of a guided vault choice
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/n0mad-ai/bastra-recall/issues/178 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。

## 17. 安装坑 · 来源证据：test: verify the Ollama fresh-install (brew) path on a clean macOS env

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：test: verify the Ollama fresh-install (brew) path on a clean macOS env
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/n0mad-ai/bastra-recall/issues/90 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。

## 18. 安装坑 · 来源证据：uninstall all: skill kept as 'shared with Claude Desktop' although Desktop was uninstalled in the same run

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：uninstall all: skill kept as 'shared with Claude Desktop' although Desktop was uninstalled in the same run
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/n0mad-ai/bastra-recall/issues/181 | 来源类型 github_issue 暴露的待验证使用条件。

## 19. 配置坑 · 可能修改宿主 AI 配置

- 严重度：medium
- 证据强度：source_linked
- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- 证据：capability.host_targets | https://github.com/n0mad-ai/bastra-recall | host_targets=mcp_host, claude_code, claude, cursor, chatgpt

## 20. 配置坑 · 失败模式：configuration: Vault self-audit surfaced as Markdown in the vault (Obsidian as the viewer) — conflicts, dema...

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: Vault self-audit surfaced as Markdown in the vault (Obsidian as the viewer) — conflicts, demand-gaps, dangling
- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Vault self-audit surfaced as Markdown in the vault (Obsidian as the viewer) — conflicts, demand-gaps, dangling
- 证据：failure_mode_cluster:github_issue | https://github.com/n0mad-ai/bastra-recall/issues/140 | Vault self-audit surfaced as Markdown in the vault (Obsidian as the viewer) — conflicts, demand-gaps, dangling

## 21. 配置坑 · 失败模式：configuration: curator phase A: deterministic usage-driven staleness pass (score-only, idle-gated)

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: curator phase A: deterministic usage-driven staleness pass (score-only, idle-gated)
- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: curator phase A: deterministic usage-driven staleness pass (score-only, idle-gated)
- 证据：failure_mode_cluster:github_issue | https://github.com/n0mad-ai/bastra-recall/issues/155 | curator phase A: deterministic usage-driven staleness pass (score-only, idle-gated)

## 22. 配置坑 · 失败模式：configuration: telemetry: per-memory usage sidecar — append-only aggregate of surfaced/loaded/acted_on

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: telemetry: per-memory usage sidecar — append-only aggregate of surfaced/loaded/acted_on
- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: telemetry: per-memory usage sidecar — append-only aggregate of surfaced/loaded/acted_on
- 证据：failure_mode_cluster:github_issue | https://github.com/n0mad-ai/bastra-recall/issues/154 | telemetry: per-memory usage sidecar — append-only aggregate of surfaced/loaded/acted_on

## 23. 配置坑 · 失败模式：configuration: v0.7.0-beta.1 — Recall that proves itself

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: v0.7.0-beta.1 — Recall that proves itself
- 对用户的影响：Upgrade or migration may change expected behavior: v0.7.0-beta.1 — Recall that proves itself
- 证据：failure_mode_cluster:github_release | https://github.com/n0mad-ai/bastra-recall/releases/tag/v0.7.0-beta.1 | v0.7.0-beta.1 — Recall that proves itself

## 24. 配置坑 · 失败模式：configuration: v0.7.0-beta.4

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: v0.7.0-beta.4
- 对用户的影响：Upgrade or migration may change expected behavior: v0.7.0-beta.4
- 证据：failure_mode_cluster:github_release | https://github.com/n0mad-ai/bastra-recall/releases/tag/v0.7.0-beta.4 | v0.7.0-beta.4

## 25. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/n0mad-ai/bastra-recall | README/documentation is current enough for a first validation pass.

## 26. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/n0mad-ai/bastra-recall | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/n0mad-ai/bastra-recall | no_demo; severity=medium

## 28. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/n0mad-ai/bastra-recall | no_demo; severity=medium

## 29. 安全/权限坑 · 来源证据：curator phase A: deterministic usage-driven staleness pass (score-only, idle-gated)

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：curator phase A: deterministic usage-driven staleness pass (score-only, idle-gated)
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/n0mad-ai/bastra-recall/issues/155 | 来源类型 github_issue 暴露的待验证使用条件。

## 30. 安全/权限坑 · 来源证据：telemetry: per-memory usage sidecar — append-only aggregate of surfaced/loaded/acted_on

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：telemetry: per-memory usage sidecar — append-only aggregate of surfaced/loaded/acted_on
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/n0mad-ai/bastra-recall/issues/154 | 来源类型 github_issue 暴露的待验证使用条件。

## 31. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/n0mad-ai/bastra-recall | issue_or_pr_quality=unknown

## 32. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/n0mad-ai/bastra-recall | release_recency=unknown

<!-- canonical_name: n0mad-ai/bastra-recall; human_manual_source: deepwiki_human_wiki -->