@bastra-recall /守护进程
MCP服务器+ HTTP网关后面的基础架构召回。观察markdown vault，使用BM25 +可选嵌入对其进行索引，并在studio MCP和HTTP REST上公开稳定的工具表面。
有关项目级文档（远景、安装、REST API、路线图），请参阅 顶级的自述 和 PLAN.md.
它是做什么的
- 监视的目录
.md带有YAML前文（模式）的文件../../docs/memory-schema.md）。 - 索引通过
minisearchBM25;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登录。 远程访问 |
| 钩子 | 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） |
安装+注册
看到 顶级的自述． 路径，按摩擦的顺序：
curl -fsSL https://bastra.io/install | bash-安装Homebrew + tap + binary +运行引导安装。推荐的非开发人员路径。Install Bastra.command双击 -相同的步骤，但浏览器下载被隔离并且模式为644，因此需要右键单击→打开（#320）。bastra install all-单个CLI调用，注册MCP + Skill +默认的静默钩子，横跨Claude Code， Claude Desktop， Codex/ChatGPT Desktop和Cursor。在没有配置保险库的情况下首次运行时，将提供一个交互式安装来创建~/BastraVault为你(非互动/--yes/--dry-run运行保持确定性错误)。- 完全手动的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)，不会匹配。请使用端口：
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客户端连接之前需要守护进程，显式启动它：
bastra-recall &
开发工作流程
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秒后触发 用法 |
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 (# 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 对于全内存前端事务规范，守护进程通过 zod 加载时，将跳过验证失败的文件，并发出错误警告。
限制
- 共享的过程。 转发器根据需要启动守护进程。在macOS,
bastra autostart on管理一个可选的LaunchAgent来保持它的运行；使用bastra autostart off回到按需操作。 - 云存储挂载 （谷歌驱动器，iCloud, Dropbox）需要轮询模式在chokidar -默认启用，但手表延迟可能是几秒钟。
- 游标规则是针对每个项目的。
bastra install cursor寄存器MCP。运行bastra rules cursor在每个项目内部安装共享内存指南。