Bastra Recall

Bastra Recall

English · Deutsch

🇬🇧 English

少重复劳动。让 AI 工具共享同一份记忆。

我们的目标是为日常 AI 工作打造最出色的个人记忆——开放、透明，并由你掌控。

让你的偏好、决策和来之不易的解决方案不再局限于单次聊天。Bastra Recall 会将它们保存为电脑上易读的 Markdown 文件，并提供给已连接的 AI 助手。

Recall 的用途提供了关于对话、规则、任务、文档和协作的实用示例。

主动任务仍为可选预览功能，在 v1.2.0 发布前默认关闭。若要试用，请在守护进程和客户端／钩子中设置 BASTRA_TASKS=1，然后重启。参见预览说明和限制。

受支持的集成可帮助助手保存有用经验，并在开始工作前检索相关记忆。你可以使用 Obsidian 或任何文本编辑器自行检查和编辑这些文件。自动回忆取决于客户端集成和助手，并不能保证每条指令都会得到遵循。

为什么不直接用 CLAUDE.md？

在内容较少时，CLAUDE.md 或 AGENTS.md 很好用。项目每多开展一个月，文件就会变得更长，而助手每次会话都会收到全部内容，无论是否需要。最终无人维护，约定又会逐渐偏离。

Bastra Recall 正好可以解决这些问题：

• 按需提供，而非一股脑全给： 每个决策和经验都单独保存为一个文件。受支持的集成会在工作开始前提供相关条目，而不是每次都发送全部内容。
• 随工作不断增长： 助手可以在工作过程中记录新的决策和已解决的问题。你可以按需审核和更正，无须手动添加所有内容。
• 多个工具共享同一份记忆： Claude Code、Codex 和其他支持 MCP 的工具共用同一个知识库，因此你不必维护多份规则文件并确保它们同步。

保留你的 CLAUDE.md。Recall 会补充那些不适合放进每次会话中的知识。

1.1.1 版本现已发布。 在最新版本中查找已发布的下载，在更新日志中查看更改，并在支持矩阵中查看经过测试的集成。

_{cmux 中 Claude Code + Codex 的真实会话：两个 Agent 都使用 Recall 并交流发现，同时显示实时 Ember 面板。精选片段。}

观看 1080p 演示

https://github.com/user-attachments/assets/58e68703-8b0d-46c3-b468-33063e8ebf83

1.1.1 修复了后继项排序、反射词形、并发保存和锁、代码图刷新开销、Linux 监视、状态栏更新以及提示块边界问题。支持 Node 22–26。更新日志 · 状态栏。

安装

macOS — 引导式设置：

curl -fsSL https://bastra.io/install | bash

如果尚未安装 Homebrew，脚本会先安装它，然后安装 Bastra Recall 并启动设置。选择存放记忆的文件夹，以及要连接的 AI 客户端。如果你更愿意先查看安装脚本再运行，请阅读安装脚本。

macOS 或 Linux — 使用 Node 22–26：

npx bastra-recall install

无需预先全局安装 npm。或者：npm install -g bastra-recall，然后运行 bastra install。

设置完成后，重启 AI 客户端。Claude Desktop 需要进行一次性记忆设置；Codex 用户应按照 Codex 指南中的说明检查并信任已安装的钩子。

运行 bastra doctor 检查设置；bastra doctor --fix 会修复注册项。其功能部分会列出你启用或关闭的 Recall 功能——记忆语言、引导流程、语义回忆、每个客户端的钩子和技能，以及可选择启用的额外功能；每个关闭的项目旁都列有启用它的命令。其他安装方式介绍了 macOS 下载、源码构建和手动配置。

尝试保存你的第一条记忆

1. 告诉助手：“记住：对于这个项目，请简要说明你所做的更改，并说明如何检查这些更改。”
2. 让它显示已保存的记忆，以便你检查措辞。
3. 开始一个新会话，然后询问：“我在这个项目中解释更改时有什么偏好？”

你可以在另一个已连接的客户端中使用同一个知识库重复查询。这是检查工具是否共享记忆的简单方法；受支持的钩子还会在日常工作中帮助显示相关上下文。

支持的客户端

AI 客户端	状态	设置与行为
Claude Code	已测试 — 日常使用中	MCP、Skill、十个钩子注册项（不含 Stop/SessionEnd 时为八个）、保存通知和状态栏。钩子
Claude Desktop	已测试	MCP 和记忆指南；首次调用工具时提供会话上下文。设置，包括 macOS .mcpb 扩展
Codex CLI	已针对 v1.0 集成验证	MCP、Skill 和原生钩子。设置
Codex IDE + ChatGPT Desktop	已实现；尚未进行实地测试	共享本地 Codex 配置。设置与限制
Cursor	已实现；尚未进行实地测试	MCP 注册；使用 bastra rules cursor 添加项目规则
ChatGPT Custom GPT Actions	计划中	REST API 和入门架构已就绪；打包的集成尚未准备好。跟踪进度

其他 MCP 客户端可以通过转发器连接，但尚未经过测试。脚本和其他集成可以使用 REST API。MCP 是一种协议，可让 AI 助手使用外部工具，例如此记忆服务。

支持的平台

平台	状态	可用性
macOS（Apple Silicon 和 Intel）	支持	通过 Homebrew 和 npm 安装，bastra autostart，Claude Desktop .mcpb 扩展（发布版本附带经过验证的已编译钩子客户端清单，与 npm 版本相同；只有在你选择启用后才会下载客户端本身）、open_document 和已编译的钩子客户端
Linux（x86_64 和 arm64）	守护进程、CLI、MCP 和钩子	使用 npm 安装；提供已编译的钩子客户端。不支持通过 Homebrew 安装、macOS LaunchAgent（bastra autostart）、安装 .mcpb 扩展或使用 open_document。转发器会按需启动守护进程。
Windows（x64）	仅进行实验性准备	已配置钩子客户端的交叉构建和 .exe 注册；尚未验证可执行文件的生成和实际 Windows 使用情况。验收待完成（#348）。

为什么

周一做出的项目决定，即使你切换了 AI 工具，周四仍然应该能用。Bastra Recall 为这些工具提供了一个共享的查阅位置：

• **留存有用的上下文：**偏好、决定、项目事实，以及已解决问题的经验教训。
• **开始工作前回忆：**受支持的钩子会在会话开始时和执行操作前呈现上下文；共享 Skill 会引导助手自行搜索和保存。
• **掌控文件：**记忆以纯 Markdown 和结构化元数据保存，可在 Bastra 之外读取和编辑。
• 查看已记住的内容：bastra map 会打开本地知识库地图，供你浏览、搜索和维护记忆。

一个工作周中的示例展示了这些功能如何协同工作。

代码感知（实验性）

此功能为实验性且可选，默认关闭；你可以在每个仓库中通过 bastra code enable 启用。启用后，Recall 会在助手编辑文件前告知它还有哪些文件导入或调用该文件中的内容；并添加 find_code 查找功能，让你可以按名称查找符号，而无需使用 grep。代码地图由 Graphify 在本地构建，只读取代码，绝不会提交，也不会让任何大模型看到你的源代码。它可以帮助 Agent 在陌生或大型仓库中找到方向；但对于“如果我更改这个，会有哪些内容受到影响”，在类似我们这样的仓库中，它的效果并未显著优于普通搜索，而且会占用上下文和后台 CPU。使用方法。目前支持 macOS 和 Linux。

隐私与控制

存储和关键词搜索均在本地进行。助手检索到记忆时，会将其内容作为上下文接收；基于云的助手可能会通过其服务提供商处理这些内容。本地存储并不意味着整个 AI 会话都在离线状态下进行。

语义搜索为可选功能。bastra embeddings on 会设置本地 Ollama 嵌入；bastra embeddings off 会切回关键词搜索。启用 Ollama 嵌入后，也会启动后台释义处理（doc2query）：本地生成模型会改写每条记忆的触发条件；在没有 GPU 的机器上，这会耗费数小时的 CPU 时间。在守护进程的环境中设置 BASTRA_TRIGGER_EXPAND=0 可关闭此功能；embeddings on 和 bastra doctor 会显示使用的模型。明确选择 OpenAI 嵌入时，查询和已索引的记忆文本会发送到 OpenAI。隐私与网络使用说明了这些数据处理途径、文件同步和可选的网络功能。

存放在 iCloud、Google Drive 或 Dropbox 中的知识库会使用相应服务的同步功能。多台电脑上的并发编辑可能导致冲突，包括与 Bastra 自动更新元数据时发生的冲突。Bastra 不提供托管式多设备同步。请做好备份，并在替换文件前检查是否存在冲突副本。

如果 ~/.bastra/vault-roots.json 中记录的知识库根目录后来消失（例如，其所在的驱动器未挂载），/health 和回忆功能会报告 vault_missing，写入程序也会拒绝在磁盘上将其重新创建为空文件夹。首次保存时仍会创建全新的路径，但只会创建一层：其父文件夹必须已存在。如果父文件夹也不存在（常见于驱动器未挂载的情况），保存会停止并报错，指出缺失的父文件夹；请先挂载驱动器或创建父文件夹。bastra install --vault <path> 和设置向导是例外：你会在那里指定路径，因此它们会自行创建缺失的父文件夹。在从未见过某个路径的机器上，Bastra 无法完全区分新知识库与父文件夹已存在但驱动器未挂载的情况，因此首次保存前请检查驱动器是否已挂载。如果 ~/.bastra/vault-roots.json 为空或已损坏，或 ~/.bastra 不可写，所有知识库写入操作都会停止，并报错指出相应文件：如果知识库所在的驱动器已挂载，请删除该文件（下次保存时会重新写入）；否则请修复 ~/.bastra 的权限。如果你是有意移动或删除知识库，请重新创建该文件夹，或将 Bastra 指向新路径。

指南

• Doctor — 设置、缺少保存提示和守护进程配置警告。

• Telemetry — 已交付的上下文、候选项和可衡量的成本。

• Release checks — 验证完整的已发布内容。

• 导入现有记忆 — 列表、聊天导出、规则和记忆文件夹。文件夹导入会直接进入单独的接收区；其他方式则会暂存候选项以供审核。

• 知识库地图 — 浏览、搜索记忆，并标记需要维护的内容。

• 更新 — 使用 bastra update 更新，或选择启用自动更新。

• 模型建议 — 某个版本可能会推荐更合适的本地文本模型；系统会征求你的同意，绝不会自动切换。

• 已审核的遗漏收集器 — 用于审核遗漏召回机会的离线仓库工具；不会自动应用任何内容。

• 状态栏和终端面板 — Claude Code 和 Codex 的设置、视图和数据限制。

• 产品文档 — 让助手为你的项目维护用户指南。

• Bastra Commons — 可选的社区方案，附带验证记录。

• 使用说明和故障排查 · 记忆格式 · 架构 · 钩子 · 归档 rm 和 git 快照 · 保存和召回触发条件 · 分类体系 · 情感效价和反射

路线图

1.x 版本系列专注于可衡量的召回质量、相关的会话上下文，以及对记忆使用更清晰的控制。累计会话上下文预算目前正在影子模式下进行测量；它尚未对整个实时会话强制执行上限。路线图和版本边界。

原生 Bastra Mac 应用正在开发中。开源软件包已包含本地的浏览器版知识库地图，可独立于该应用运行。

许可证和联系方式

MIT — 请参阅 LICENSE。状态栏包含 owloops/claude-powerline，并保留其 MIT license。可选的代码感知功能使用 Graphify（Apache-2.0）；这是一个独立项目，Recall 不会将其打包在内。只有在启用该功能时，才会从 PyPI 安装它。

提问 · 报告错误 · 参与贡献 · 支持该项目。请通过 SECURITY.md 私下报告漏洞。

由 Daniel / @n0mad-ai 构建。

---

🇩🇪 德语

少重复。为你的 AI 工具打造共享记忆。

我们的目标是打造最适合日常 AI 工作的个人记忆系统——开放、透明，并由你掌控。

跨越不同聊天，保存你的偏好、决策和已找到的解决方案。Bastra Recall 会将它们保存为你电脑上的 Markdown 文件，并提供给你连接的 AI 助手使用。

Recall 的用途展示了对话、规则、任务、文档和协作的示例。

主动任务仍为选择加入的预览功能，在 v1.2.0 之前默认关闭。如需试用，请为守护进程和客户端/钩子设置 BASTRA_TASKS=1，然后重启它们。预览指南和限制。

受支持的集成可帮助助手保存重要发现，并在开始新任务前检索相关记忆。你可以使用 Obsidian 或任何文本编辑器检查和编辑这些文件。自动检索取决于集成和助手；它无法保证每条指令都会得到遵循。

为什么不直接用 CLAUDE.md？

只要文件保持简短，CLAUDE.md 或 AGENTS.md 就很实用。随着项目持续数月，文件会越来越长，而助手每次会话都会收到全部内容，不管是否需要。最终，没人再维护它，约定也会再次变得不一致。

Bastra Recall 正是为解决这些问题而设计：

• 按需提供，而不是一股脑全给： 每项决策和经验都单独保存为一个文件。受支持的集成会在开始工作前显示相关条目，而不是每次都把全部内容发过去。
• 随工作不断积累： 助手可以在工作过程中自行记录新的决策和已解决的问题。你可在需要时检查并更正，而不必手动补录所有内容。
• 多个工具共享同一份记忆： Claude Code、Codex 和其他兼容 MCP 的工具都能访问同一个保险库，无需协调不同的规则文件。

你的 CLAUDE.md 可以保留。Recall 会补充那些不适合放进每次会话的知识。

1.1.1 版本现已发布。 已发布的下载内容见最新版本，变更见更新日志，经过测试的集成见支持矩阵。

_{Claude Code 和 Codex 在 cmux 中真实协作：双方都使用 Recall 并交流发现，Ember 显示实时数据。录制内容经过剪辑。}

观看 1080p 演示

https://github.com/user-attachments/assets/58e68703-8b0d-46c3-b468-33063e8ebf83

1.1.1 修复了已被替代的笔记的搜索顺序、反思中的词形处理、并行保存和锁定、代码图谱开销、Linux 监视、状态栏以及提示块边界问题。支持 Node 22–26。更新日志 · 状态栏。

安装

macOS – 引导式设置：

curl -fsSL https://bastra.io/install | bash

脚本会在需要时安装 Homebrew，安装 Bastra Recall 并启动设置。选择存放记忆的文件夹，以及要连接的 AI 客户端。你可以先阅读安装脚本。

macOS 或 Linux – 使用 Node 22–26：

npx bastra-recall install

无需预先全局安装 npm。或者：npm install -g bastra-recall，然后运行 bastra install。

设置完成后，重新启动 AI 客户端。Claude Desktop 需要进行一次性 Memory 设置；对于 Codex，请按照 Codex 指南中的说明检查并确认已安装的 Hooks。

bastra doctor 会检查设置；bastra doctor --fix 会修复注册信息。features 部分会显示哪些 Recall 功能已启用或关闭——Memory 语言、引导、语义 Recall、Hooks 和各客户端的 Skill，以及可选附加功能——并列出每项已关闭功能的启用命令。其他安装方式介绍了 macOS 下载、从源代码构建和手动配置。

试用你的第一条记忆

1. 对助手说：“记住：简要说明此项目中的变更，并说明你如何验证这些变更。”
2. 让助手显示已保存的记忆，以便检查措辞。
3. 开启新会话，并询问：“我喜欢如何说明此项目中的变更？”

如有需要，可以在另一个连接到同一 Vault 的客户端中重复提问。这样便能轻松确认你的工具是否使用了同一条记忆。受支持的 Hooks 还会在日常工作中帮助显示相关上下文。

支持的界面

AI 客户端	状态	设置与行为
Claude Code	已测试 – 日常使用中	MCP、Skill、十个 Hook 注册（不含 Stop/SessionEnd 时为八个）、记忆提示和状态栏。Hooks
Claude Desktop	已测试	MCP 和 Memory 指南；首次调用工具时提供会话上下文。设置，包括 macOS 扩展 .mcpb
Codex CLI	已验证适用于 v1.0 集成	MCP、Skill 和原生 Hooks。设置
Codex IDE + ChatGPT Desktop	已实现；尚未在实际环境中测试	共用本地 Codex 配置。设置与限制
Cursor	已实现；尚未在实际环境中测试	MCP 注册；使用 bastra rules cursor 添加项目规则
ChatGPT Custom GPT Actions	计划中	已提供 REST API 和入门 Schema；完整集成仍待完成。进展

其他 MCP 客户端可以使用转发器，但尚未经过测试。脚本和其他集成可使用 REST API。MCP 是一种协议，AI 助手可借此使用此类记忆服务等外部工具。

支持的平台

平台	状态	可用功能
macOS（Apple Silicon 和 Intel）	支持	可通过 Homebrew 和 npm 安装；支持 bastra autostart、Claude 桌面扩展 .mcpb（发布构建与 npm 包一样，包含经过验证的已编译 Hook 客户端清单；只有在你同意后才会下载客户端本身）、open_document 和已编译的 Hook 客户端
Linux（x86_64 和 arm64）	Daemon、CLI、MCP 和 Hooks	可通过 npm 安装；提供已编译的 Hook 客户端。不支持 Homebrew 安装、macOS LaunchAgent（bastra autostart）、.mcpb 扩展安装或 open_document。Forwarder 会按需启动 Daemon。
Windows（x64）	实验性准备	已配置 Hook 客户端的交叉构建和 .exe 注册；尚未验证可执行文件的生成及其在真实 Windows 环境中的使用。验收待完成（#348）。

为什么

周一做出的项目决策，到周四仍然应该可用，即使你换了 AI 工具。Bastra Recall 为你的工具提供了一个共同的起点：

• **保留有用的上下文：**偏好、决策、项目信息，以及从已解决问题中获得的经验。
• **开始工作前先回顾：**受支持的 Hooks 会在会话开始和执行操作前提供上下文；共享技能则会引导助手自行搜索和保存。
• **保留文件：**记忆采用带有结构化元数据的 Markdown 格式，在 Bastra 之外也可以读取和编辑。
• 了解已保存的内容：bastra map 会打开本地 Vault 地图，方便浏览、搜索和维护。

一周工作示例展示了它们如何协同工作。

代码感知（实验性）

此功能为实验性，可选且默认关闭；可在每个仓库中通过 bastra code enable 启用。启用后，Recall 会在助手修改文件前告知它还有哪些文件导入或调用了该文件；此外，find_code 可以按名称查找符号，而不是搜索它。代码地图会在本地构建 Graphify，只读取代码，绝不会被提交，也不会有语言模型看到你的源代码。它可以帮助 Agent 熟悉陌生或大型仓库；但对于“修改这个会导致什么问题？”，在像我们这样的仓库中，它的表现并未明显优于简单搜索，而且会在后台消耗上下文和计算资源。了解如何使用。目前支持 macOS 和 Linux。

隐私与控制

存储和关键词搜索都在本地进行。助手检索某条记忆时，会将其内容作为上下文接收；基于云端的助手可能会在其提供商处处理这些内容。本地存储并不意味着整个 AI 会话都处于离线状态。

语义搜索是可选的。bastra embeddings on 会设置本地 Ollama 嵌入；bastra embeddings off 会切换回关键词搜索。启用 Ollama 嵌入后，后台改写（doc2query）也会启动：本地生成模型会改写每条记忆的触发词，在没有 GPU 的电脑上可能需要数小时。将 BASTRA_TRIGGER_EXPAND=0 设为守护进程的环境变量即可跳过此过程；embeddings on 和 bastra doctor 会显示所用模型。如果你明确选择 OpenAI 嵌入，搜索查询和已索引的记忆文本会发送到 OpenAI。隐私与网络访问 说明了这些数据流、文件同步和可选网络功能。

存储在 iCloud、Google Drive 或 Dropbox 中的 Vault 会使用相应服务的同步功能。多台电脑同时进行更改可能会产生冲突，Bastra 自动更新元数据时也可能发生这种情况。Bastra 不提供托管式多设备同步。请保留备份，并在替换文件前检查冲突副本。

如果 ~/.bastra/vault-roots.json 中记录的 Vault 根目录后来消失（例如，因为其所在的驱动器未挂载），/health 和 Recall 会报告 vault_missing，写入器也不会在磁盘上将其重新创建为空文件夹。首次保存时仍会创建全新的路径，但只会创建一层：其父文件夹必须已经存在。如果父文件夹也不存在（通常是因为驱动器未挂载），保存会失败，并报错指出该文件夹；请挂载驱动器，或先创建父文件夹。例外情况是 bastra install --vault <pfad> 和设置向导：由于你在其中自行指定路径，它们会自行创建缺失的父文件夹。在从未见过某个路径的机器上，如果其父文件夹存在，Bastra 无法可靠地区分全新的 Vault 和缺失的驱动器。因此，首次保存前请确认驱动器已挂载。如果 ~/.bastra/vault-roots.json 为空或已损坏，或者 ~/.bastra 不可写入，任何 Vault 写入操作都会停止，并报错指出该文件：如果 Vault 已挂载，请删除该文件（下次保存时会重新写入）；否则，请修正 ~/.bastra 的权限。如果你是有意移动或删除了 Vault，请重新创建该文件夹，或向 Bastra 提供新路径。

指南

• Doctor – 设置、缺失的存储提示和守护进程配置警告。

• 遥测 – 已提供的上下文、候选项和可衡量的成本。

• 发布检查 – 检查完整的已发布套件。

• 导入现有记忆 – 列表、聊天导出、规则和记忆文件夹。文件夹导入会直接进入单独的区域；其他方式会准备候选项供审核。

• Vault 地图 – 浏览、搜索记忆并标记记忆以便维护。

• 更新 – 使用 bastra update 更新或启用自动更新。

• 模型建议 – 发布版本可能会建议更合适的本地文本模型；系统会询问你，绝不会自动切换。

• Reviewed-Miss-Harvester — 一款离线仓库工具，用于检查错失的检索机会；不会自动应用任何更改。

• 状态栏和终端面板 – Claude Code 和 Codex 的设置、视图和数据边界。

• 产品文档 – 让助手维护项目指南。

• Bastra Commons – 可选的社区配方，附带审核证明。

• 使用与故障排除 · 记忆格式 · 架构 · 钩子 · 归档 rm 和 Git 快照 · 存储和检索触发器 · 分类体系 · 效价与反射

路线图

1.x 发布系列专注于衡量检索质量、提供恰当的会话上下文，以及更清晰地控制记忆的使用。会话的累计上下文预算目前在影子模式下进行测量，尚未强制实施全局上限。路线图和发布边界。

原生 Bastra Mac 应用正在开发中。开源套件已包含本地浏览器版 Vault 地图，可独立于该应用运行。

许可证与联系

MIT——请参阅 LICENSE。状态栏包含 owloops/claude-powerline，并沿用其 MIT 许可证。可选的代码感知功能使用 Graphify（Apache-2.0）；这是一个独立项目，不随 Recall 一同提供；只有在启用该功能时才会从 PyPI 安装。

提问 · 报告问题 · 参与贡献 · 支持项目。安全问题请通过 SECURITY.md 保密报告。

由 Daniel / @n0mad-ai 构建。