bd recall 命令深度指南用 Beads 按 key 检索持久记忆【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads导读bd recall key是 Beads 持久记忆体系memory plane的核心读取命令用于按 key 检索一条记忆的完整内容。它由 docs/cli-reference/recall.md 定义是bd remember/bd memories/bd forget组成的记忆四命令之一remember写入、recall读取、memories枚举搜索、forget删除。读完本文你将掌握bd recall的完整用法、JSON 与退出码契约、未命中行为以及它背后从 CLI 前端到memoryops角色契约再到kv.memory.存储编码的完整调用链并能直接把它接入 Agent 的会话钩子与自动化脚本。命令概览与基本用法bd recall是一个顶层命令属于setup命令组功能定位为Retrieve the full content of a memory by its key按 key 检索一条记忆的完整内容。它的命令语法为bd recall key [flags]来自官方文档的示例bd recall dolt-phantoms bd recall auth-jwt用法要点必须且只能接收一个位置参数key在 cmd/bd/memory.go 中通过Args: cobra.ExactArgs(1)约束传入多于或少于一个参数都会直接报错不会执行任何读取key 就是记忆的名字key 可以由bd remember从内容自动派生slug也可以用--key显式指定bd recall只负责按这个名字把整条记忆取回来读取的是完整内容与bd memories列表里做了单行截断truncateMemory把换行替换为空格并截断到 120 字符的预览不同bd recall返回的是存储时的原文多行内容、Unicode、前后空格都逐字节保留。前置条件直接数据库访问recall在RunE中通过openMemories(recall requires direct database access)获取持久记忆的访问句柄cmd/bd/memory.go。openMemories会做双路线分派若当前调用处于代理服务器proxied路线如通过bd serve起的 HTTP 后端则经由proxiedMemories从 UOW provider 获取受保护的内存面否则要求直接模式direct mode必须在已初始化的 workspace/仓库内运行且底层存储Dolt 数据库可用否则命令会以明确提示失败。因此bd recall并非纯粹的字符串工具它读的是工作区自己的持久化记忆库——记忆存放在 Dolt 工作集里跨会话、跨账号轮换依然存在。命中与未命中输出与退出码契约recall的输出渲染由printRecallResult完成cmd/bd/memory.go它对找到与未找到两种结局给出了完全不同的契约。找到记忆时的文本输出$ bd recall dolt-phantoms Dolt phantom DBs hide in three places: ...找到时记忆的完整内容被原样打印到 stdoutfmt.Printf(%s\n, value)不做任何截断换行保持原样退出码为 0可以直接用于 shell 管道或变量捕获。未找到时的 SilentExit 契约$ bd recall no-such-key No memory with key no-such-key提示信息写入stderrfmt.Fprintf(os.Stderr, ...)stdout 保持干净随后调用SilentExit()以非零退出码静默退出不再打印任何 usage 帮助信息。对 Agent 和脚本而言这个契约非常重要判定未命中应该看退出码而不是解析 stdout。未命中不是 Go 层面的错误Recall对未知 key 返回Foundfalse, nil error而是前端把结果未找到翻译成了退出码信号这与bd config get等读取类命令的未命中约定一致。JSON 输出模式bd recall支持全局--json输出。JSON 模式下命中返回{key: dolt-phantoms, value: Dolt phantom DBs hide in three places: ..., found: true}未命中返回{key: no-such-key, value: , found: false}随后同样走SilentExit()非零退出。注意 JSON 里用found字段显式区分记忆存在但内容为空串与记忆不存在两种语义避免下游把空字符串误读成有效内容。底层角色契约memoryops.Memoriesbd recall的前端逻辑非常薄——它只负责参数校验、路由分派和输出渲染真正的读取语义由memoryops.Memories接口承担memoryops/memories.go。这是 Beads 的角色role架构CLI、HTTP 门面、代理服务器共用同一套契约保证各路线行为一致。接口中与 recall 相关的定义type RecallRequest struct{ Key string } type RecallResult struct { Key string Value string Found bool } Recall(ctx context.Context, req RecallRequest) (RecallResult, error)几个值得注意的语义均写在该文件的文档注释中属于明确的设计决策Recall是纯读操作不记录历史、不触发 completion 钩子、不修改任何行未命中的 key 返回Foundfalse且 error 为 nil绝不是ErrNotFound——因为底层存储无法区分配置行不存在与行存在但存的是空字符串这两种情况见 memoryops/errors.go角色层面拒绝编造它看不见的区分memoryops特意不导出ErrNotFound就是为了把这个决定钉死Found的语义是Value ! 一条以空串存储的记忆与一条不存在的记忆对Recall而言是同一个答案唯一能区分它们的是bd memorieskey 存在就会被枚举出来。而前端remember拒绝存储空内容所以正常流程不会制造这种歧义只有绕过前端的带外写入才会。recallCmd的RunEcmd/bd/memory.go把这一切串起来打开记忆面 → 构造RecallRequest{Key: args[0]}→ 调用memories.Recall→ 交给printRecallResult渲染。整个命令只有这四步错误则统一走HandleErrorRespectJSON自动感知 JSON 模式决定输出格式。key 校验规则请求进入角色前key 会经过memoryapi.ValidateKeyinternal/memoryapi/memoryapi.go校验空白 key 属于确定性校验失败ErrValidation因为空 key不存在任何调用者能指代的记忆行回答Foundfalse等于为一个从未被提出的问题作答。校验通过后 key原样返回、不做任何裁剪——bd remember --key接受任意字符串一个仅靠空格与其他 key 区分的 key 可能是调用者真实持有的裁掉空格就会答非所问。存储编码kv.memory. 前缀与合并语义记忆并不存在单独的数据库表里而是存放在与配置共享的同一张表中但位于保留命名空间下memoryops/doc.go。一条名为dolt-phantoms的记忆实际存储的配置键是kv.memory.dolt-phantoms前缀kv.memory.的唯一权威定义在 internal/storage/kvkeys常量memoryPrefixcmd/bd/memory.go 直接引用它。这套编码有两个关键推论合并即收敛存储层的 merge resolver 只有在冲突键全部带kv.memory.前缀时才用--theirs自动消解配置冲突见internal/storage/versioncontrolops/mergesettle.go。也就是说拉取后自动收敛是记忆这个概念的组成部分——而普通设置行没有这个待遇。这正是记忆与设置分开成两个角色memoryops与issueops.WorkspaceConfig的根本原因按前缀隔离bd memories枚举时只会看到记忆平面设置行、通用bd kv行永远不会混进来反过来bd recall也只认kv.memory.下的行。一个 shadow 了设置名的记忆 key如kv.memory.issue_prefix只是叫issue_prefix的记忆不会与真正的设置混淆。用户侧的所有请求与结果都只携带用户 key不带前缀前缀的拼写是存储实现层的私事这样角色契约就与编码解耦避免两处拼写漂移。与 remember 的联动bare key 的欲望路径bd recall还隐身在bd remember里bd remember bare-slug在特定条件下会转为读取而非写入cmd/bd/memory.go。逻辑是当没有显式--key、且位置参数内容经DeriveKey往返后原样不变即它本身就是个 slug而不是一句人话时若该 key 已存在 →直接执行一次Recall等价于bd recall key并在 stderr 提示(recalled ... -- a bare existing key READS. To overwrite: bd remember new content --key key)若该 key 不存在 → 拒绝写入提示没有名为 X 的记忆可读取且拒绝把裸 key 当内容存储。这正是bd recall命令在 docs/cli-reference/recall.md 中两个示例dolt-phantoms、auth-jwt的来源——它们与bd remember文档中的--key示例docs/cli-reference/remember.md互相呼应构成一个完整的记忆写入-检索闭环。该路径的集成测试见 cmd/bd/memory_proxied_integration_test.go覆盖了多行内容经 recall 逐字节往返、未命中 recall 的失败输出、以及 bare existing key 读取代写等场景。在 Agent 工作流中的典型用法记忆的写入端是bd remember读取端是bd recall而bd primecmd/bd/prime.go会在会话启动时把记忆批量注入给编码 AgentClaude Code、Gemini CLI、Codex 的 SessionStart 钩子让 Agent 在上下文压缩后不至于遗忘工作区约定。bd recall在此生态中的角色是按需精确读取当 Agent 需要一条特定记忆的完整细节而 prime 注入的只是摘要或列表时bd recall key是最低成本的单条读取在脚本中判断记忆是否存在依赖退出码而非文本解析需要结构化消费时加--json用found字段区分命中与空值与bd memories枚举/搜索配合先bd memories dolt找到 key再bd recall dolt-phantoms取全文。小结bd recall表面上是一行命令读一条记忆但它的每一层都体现了 Beads 持久记忆体系的设计取舍前端层有命中/未命中双契约与 JSON 输出角色层由memoryops.Memories.Recall定义纯读、Found语义与无 ErrNotFound决策存储层以kv.memory.保留前缀实现合并即收敛。把这四层串起来你就能在 Agent 会话与自动化脚本中安全、准确地消费工作区记忆。相关文档与源码入口命令文档 docs/cli-reference/recall.md、命令实现 cmd/bd/memory.go、角色契约 memoryops/memories.go、语义函数 internal/memoryapi/memoryapi.go、CLI 总览 docs/cli-reference/index.md。【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
bd recall 命令深度指南用 Beads 按 key 检索持久记忆【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads导读bd recall key是 Beads 持久记忆体系memory plane的核心读取命令用于按 key 检索一条记忆的完整内容。它由 docs/cli-reference/recall.md 定义是bd remember/bd memories/bd forget组成的记忆四命令之一remember写入、recall读取、memories枚举搜索、forget删除。读完本文你将掌握bd recall的完整用法、JSON 与退出码契约、未命中行为以及它背后从 CLI 前端到memoryops角色契约再到kv.memory.存储编码的完整调用链并能直接把它接入 Agent 的会话钩子与自动化脚本。命令概览与基本用法bd recall是一个顶层命令属于setup命令组功能定位为Retrieve the full content of a memory by its key按 key 检索一条记忆的完整内容。它的命令语法为bd recall key [flags]来自官方文档的示例bd recall dolt-phantoms bd recall auth-jwt用法要点必须且只能接收一个位置参数key在 cmd/bd/memory.go 中通过Args: cobra.ExactArgs(1)约束传入多于或少于一个参数都会直接报错不会执行任何读取key 就是记忆的名字key 可以由bd remember从内容自动派生slug也可以用--key显式指定bd recall只负责按这个名字把整条记忆取回来读取的是完整内容与bd memories列表里做了单行截断truncateMemory把换行替换为空格并截断到 120 字符的预览不同bd recall返回的是存储时的原文多行内容、Unicode、前后空格都逐字节保留。前置条件直接数据库访问recall在RunE中通过openMemories(recall requires direct database access)获取持久记忆的访问句柄cmd/bd/memory.go。openMemories会做双路线分派若当前调用处于代理服务器proxied路线如通过bd serve起的 HTTP 后端则经由proxiedMemories从 UOW provider 获取受保护的内存面否则要求直接模式direct mode必须在已初始化的 workspace/仓库内运行且底层存储Dolt 数据库可用否则命令会以明确提示失败。因此bd recall并非纯粹的字符串工具它读的是工作区自己的持久化记忆库——记忆存放在 Dolt 工作集里跨会话、跨账号轮换依然存在。命中与未命中输出与退出码契约recall的输出渲染由printRecallResult完成cmd/bd/memory.go它对找到与未找到两种结局给出了完全不同的契约。找到记忆时的文本输出$ bd recall dolt-phantoms Dolt phantom DBs hide in three places: ...找到时记忆的完整内容被原样打印到 stdoutfmt.Printf(%s\n, value)不做任何截断换行保持原样退出码为 0可以直接用于 shell 管道或变量捕获。未找到时的 SilentExit 契约$ bd recall no-such-key No memory with key no-such-key提示信息写入stderrfmt.Fprintf(os.Stderr, ...)stdout 保持干净随后调用SilentExit()以非零退出码静默退出不再打印任何 usage 帮助信息。对 Agent 和脚本而言这个契约非常重要判定未命中应该看退出码而不是解析 stdout。未命中不是 Go 层面的错误Recall对未知 key 返回Foundfalse, nil error而是前端把结果未找到翻译成了退出码信号这与bd config get等读取类命令的未命中约定一致。JSON 输出模式bd recall支持全局--json输出。JSON 模式下命中返回{key: dolt-phantoms, value: Dolt phantom DBs hide in three places: ..., found: true}未命中返回{key: no-such-key, value: , found: false}随后同样走SilentExit()非零退出。注意 JSON 里用found字段显式区分记忆存在但内容为空串与记忆不存在两种语义避免下游把空字符串误读成有效内容。底层角色契约memoryops.Memoriesbd recall的前端逻辑非常薄——它只负责参数校验、路由分派和输出渲染真正的读取语义由memoryops.Memories接口承担memoryops/memories.go。这是 Beads 的角色role架构CLI、HTTP 门面、代理服务器共用同一套契约保证各路线行为一致。接口中与 recall 相关的定义type RecallRequest struct{ Key string } type RecallResult struct { Key string Value string Found bool } Recall(ctx context.Context, req RecallRequest) (RecallResult, error)几个值得注意的语义均写在该文件的文档注释中属于明确的设计决策Recall是纯读操作不记录历史、不触发 completion 钩子、不修改任何行未命中的 key 返回Foundfalse且 error 为 nil绝不是ErrNotFound——因为底层存储无法区分配置行不存在与行存在但存的是空字符串这两种情况见 memoryops/errors.go角色层面拒绝编造它看不见的区分memoryops特意不导出ErrNotFound就是为了把这个决定钉死Found的语义是Value ! 一条以空串存储的记忆与一条不存在的记忆对Recall而言是同一个答案唯一能区分它们的是bd memorieskey 存在就会被枚举出来。而前端remember拒绝存储空内容所以正常流程不会制造这种歧义只有绕过前端的带外写入才会。recallCmd的RunEcmd/bd/memory.go把这一切串起来打开记忆面 → 构造RecallRequest{Key: args[0]}→ 调用memories.Recall→ 交给printRecallResult渲染。整个命令只有这四步错误则统一走HandleErrorRespectJSON自动感知 JSON 模式决定输出格式。key 校验规则请求进入角色前key 会经过memoryapi.ValidateKeyinternal/memoryapi/memoryapi.go校验空白 key 属于确定性校验失败ErrValidation因为空 key不存在任何调用者能指代的记忆行回答Foundfalse等于为一个从未被提出的问题作答。校验通过后 key原样返回、不做任何裁剪——bd remember --key接受任意字符串一个仅靠空格与其他 key 区分的 key 可能是调用者真实持有的裁掉空格就会答非所问。存储编码kv.memory. 前缀与合并语义记忆并不存在单独的数据库表里而是存放在与配置共享的同一张表中但位于保留命名空间下memoryops/doc.go。一条名为dolt-phantoms的记忆实际存储的配置键是kv.memory.dolt-phantoms前缀kv.memory.的唯一权威定义在 internal/storage/kvkeys常量memoryPrefixcmd/bd/memory.go 直接引用它。这套编码有两个关键推论合并即收敛存储层的 merge resolver 只有在冲突键全部带kv.memory.前缀时才用--theirs自动消解配置冲突见internal/storage/versioncontrolops/mergesettle.go。也就是说拉取后自动收敛是记忆这个概念的组成部分——而普通设置行没有这个待遇。这正是记忆与设置分开成两个角色memoryops与issueops.WorkspaceConfig的根本原因按前缀隔离bd memories枚举时只会看到记忆平面设置行、通用bd kv行永远不会混进来反过来bd recall也只认kv.memory.下的行。一个 shadow 了设置名的记忆 key如kv.memory.issue_prefix只是叫issue_prefix的记忆不会与真正的设置混淆。用户侧的所有请求与结果都只携带用户 key不带前缀前缀的拼写是存储实现层的私事这样角色契约就与编码解耦避免两处拼写漂移。与 remember 的联动bare key 的欲望路径bd recall还隐身在bd remember里bd remember bare-slug在特定条件下会转为读取而非写入cmd/bd/memory.go。逻辑是当没有显式--key、且位置参数内容经DeriveKey往返后原样不变即它本身就是个 slug而不是一句人话时若该 key 已存在 →直接执行一次Recall等价于bd recall key并在 stderr 提示(recalled ... -- a bare existing key READS. To overwrite: bd remember new content --key key)若该 key 不存在 → 拒绝写入提示没有名为 X 的记忆可读取且拒绝把裸 key 当内容存储。这正是bd recall命令在 docs/cli-reference/recall.md 中两个示例dolt-phantoms、auth-jwt的来源——它们与bd remember文档中的--key示例docs/cli-reference/remember.md互相呼应构成一个完整的记忆写入-检索闭环。该路径的集成测试见 cmd/bd/memory_proxied_integration_test.go覆盖了多行内容经 recall 逐字节往返、未命中 recall 的失败输出、以及 bare existing key 读取代写等场景。在 Agent 工作流中的典型用法记忆的写入端是bd remember读取端是bd recall而bd primecmd/bd/prime.go会在会话启动时把记忆批量注入给编码 AgentClaude Code、Gemini CLI、Codex 的 SessionStart 钩子让 Agent 在上下文压缩后不至于遗忘工作区约定。bd recall在此生态中的角色是按需精确读取当 Agent 需要一条特定记忆的完整细节而 prime 注入的只是摘要或列表时bd recall key是最低成本的单条读取在脚本中判断记忆是否存在依赖退出码而非文本解析需要结构化消费时加--json用found字段区分命中与空值与bd memories枚举/搜索配合先bd memories dolt找到 key再bd recall dolt-phantoms取全文。小结bd recall表面上是一行命令读一条记忆但它的每一层都体现了 Beads 持久记忆体系的设计取舍前端层有命中/未命中双契约与 JSON 输出角色层由memoryops.Memories.Recall定义纯读、Found语义与无 ErrNotFound决策存储层以kv.memory.保留前缀实现合并即收敛。把这四层串起来你就能在 Agent 会话与自动化脚本中安全、准确地消费工作区记忆。相关文档与源码入口命令文档 docs/cli-reference/recall.md、命令实现 cmd/bd/memory.go、角色契约 memoryops/memories.go、语义函数 internal/memoryapi/memoryapi.go、CLI 总览 docs/cli-reference/index.md。【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
)
)
