bm-setup

Basic Memory 设置

进行一场简短、灵活的访谈（约 2–3 分钟），然后编写配置。 请以对话的方式进行，并跳过根据上下文已能明显得出答案的问题（例如，如果 list_memory_projects 显示只有一个本地项目且没有云工作区，就不要询问云端／团队相关问题——只需确认即可）。每个问题都建议一个合理的默认选项，让用户只需一个词就能接受。访谈结束并确认计划前，不要进行任何写入操作。

前置条件检查

首先确认 Basic Memory MCP 服务已连接——调用 list_memory_projects。如果该工具不可用或报错，则说明 Basic Memory 尚未接入 Claude Code。先停止并指导用户完成接入（以下所有步骤都依赖它）：

1. 安装：uv tool install basic-memory --prerelease=allow（或 pip install basic-memory），版本需为 >= 0.19.0。使用 uv 时保留 --prerelease=allow：已发布的版本依赖 FastMCP 预发布版，不加此标记时，uv 会在不提示的情况下安装较旧的 Basic Memory 版本。
2. 连接：claude mcp add basic-memory -- uvx --prerelease=allow basic-memory mcp， 然后重启会话，以便加载 MCP 服务。

继续之前，重新检查 list_memory_projects——成功前不要开始访谈。

访谈

只询问无法推断的内容。涵盖以下事项：

1. 重点／用途。 “这个项目主要用于什么——代码／开发、研究、写作、知识收集、规划，还是多种用途？”这个答案会决定你建议的文件夹结构（第 4 步），并会被保存，以便 SessionStart 简报能显示相关信息。如果你是通过推断得出答案，而不是直接询问，请说明你假定的用途及其对应的结构，让用户可以用一个词纠正。

   如果用户回答代码／开发，则将其设为编码配置（sessionProfile: "coding"）：确认目录位于 Git 仓库内，解析一个稳定的 repository 标识符，例如 owner/name，来源可以是 origin 远程地址或 GitHub CLI；向用户展示并请求确认。如果远程地址缺失或有歧义，不要猜测；也不要仅因为当前目录是 Git 检出目录，就推断用户需要 coding 配置——对于混合用途，应询问此仓库是否应记录 Git 和拉取请求上下文。编码配置会初始化 Coding Session 模式，确保有意记录的检查点包含必需且可查询的 Git 身份信息（仓库、分支、SHA 和工作目录），并在存在 PR 时包含类型化的拉取请求字段。

2. 项目映射。 “你已经有用于此项目的 Basic Memory 项目了吗？还是要我新建一个？”

   • 现有项目 → 显示 list_memory_projects()，让用户选择。所选名称将成为 primaryProject。
   • 新项目 → 提议一个名称（默认：此仓库的目录名），并使用 create_memory_project 创建。
     • 本地项目（默认）：路径默认为 ~/basic-memory/<name>/；任何已连接的 Basic Memory 服务都可以创建。
     • 云项目（用户希望将内容记录到云工作区）：传入 workspace 选择器（来自 list_workspaces 的 slug）和类似 /<name> 的云端路径，并通过已连接云端的 MCP 服务创建。纯本地服务（uvx --prerelease=allow basic-memory mcp）会将该路径视为本地目录，并因此创建失败（例如，只读的 /）。如果本地服务和云端服务都已连接，则创建项目以及初始化模式都要通过云端服务进行，并将 primaryProject 固定为新项目的 external_id UUID（避免不同工作区之间发生冲突）。

3. 云端 / 团队（如果没有其他工作区，则跳过）。运行 list_workspaces。如果用户属于多个工作区，他们可能除了个人 / 默认工作区外， 还有一个团队工作区。使用 list_memory_projects 查看每个工作区中的项目（注意：不同 工作区中的项目名称可能重复，因此务必使用带工作区限定的名称，例如 my-team-2/notes，或使用 external_id UUID——绝不要只用名称）。

   • 从团队读取（推荐）：询问要将哪些团队项目纳入会话简报以便回忆。将它们的限定名称存入 secondaryProjects。这些项目为只读——回忆时会读取这些项目，但不会向其中写入内容。 **上限：**每次会话的 SessionStart 简报只读取前 6 个共享项目（受延迟 / 输出限制）， 按列表顺序读取。如果用户想要超过 6 个，请将最相关的项目排在前面，并告知他们其余项目已配置， 但不会在每次会话中读取。
   • 共享目标（可选）：如果用户想通过 /basic-memory:bm-share 向团队发布笔记，请将其添加到 teamProjects，格式为 "<qualified-name>": { "promoteFolder": "shared" }。共享始终是手动操作——自动 捕获绝不会写入团队项目。

   保持 primaryProject 为用户拥有的项目，用于他们自己的捕获；团队项目仅用于读取和有意共享。

4. 存放位置——了解或建议（取决于项目状态）。目标是准备一段简短的 placementConventions 字符串（3-6 行），说明新笔记应放在哪里。 获取方式取决于项目中是否已有笔记：

   • 已有笔记的项目 → 了解。检查项目：使用 list_directory 查看 文件夹布局，为每个文件夹抽查几篇笔记（如果某个文件夹包含重复出现的类型化笔记，还可以运行 schema_infer 了解其结构）。 总结其实际惯例——按主题组织的文件夹布局、命名风格，以及他们偏好的观察类别。根据实际笔记进行推断；不要强加规则。
   • 新建或空项目 → 建议（目前没有可供了解的内容）。根据步骤 1 中的重点，提出一个 简洁的结构——3-5 个可选的顶层文件夹，不要采用过深的分类体系——并明确说明这只是一个起点，而非脚手架：没有它也能正常记录笔记，结构可以逐步形成。不要创建空文件夹；只有笔记存入文件夹后，文件夹才会出现。让用户用一个词修改或拒绝。 无论哪种情况，都要保持简短，并将结果存为 placementConventions。SessionStart 简报会显示它（以及 captureFolder），因此它能让你的捕获内容出现在用户期望的位置——否则，存放位置只能靠猜测。

5. 架构。“我会为此配置添加会话架构，以及决策和任务架构，方便之后精确查找——可以吗？”（参见下文的“初始化架构”。）

6. 生命周期事件捕获。“默认情况下，插件会在本地记录 SessionStart 和 PreCompact 事件，用于诊断。要保持开启吗？”默认设为 开启。说明无论是否开启，常规会话简报和 PreCompact 检查点都会正常工作；捕获功能会将有限的生命周期元数据添加到本地收件箱，直到 bm hook flush 将其归档到本地。它绝不会创建知识图谱笔记。 仅当用户选择退出时，才持久化 JSON 布尔值 false。

   • 捕获内容始终保留在本地，且仅供个人使用。绝不会直接写入团队项目。

7. 希望我多主动？（输出风格）“要我主动捕获吗——回忆前先搜索知识图谱，将重要决策写成类型化笔记，并引用永久链接？还是保持安静（仅提供会话简报、PreCompact 检查点，并在需要时响应 /basic-memory:bm-remember）？”启用后会设置 outputStyle: "basic-memory"。默认启用；如果用户只希望回忆、并尽量减少干扰，则关闭。（这是控制助手主动程度的唯一设置——钩子始终会运行，无论此项如何设置。）

8. 共享技能（可选，默认是）。「想要完整的 Basic Memory 工具包—— 共享的 memory-* 技能（memory-notes、memory-tasks、memory-research、 memory-schema、memory-defrag 等）吗？我可以将它们与此插件一同安装。」 这些是规范的、与框架无关的技能（OpenClaw 打包的也是同一套）。 此插件仅包含 Claude-Code 专用的 glue，并按需获取共享技能集—— 不会在插件中附带自己的副本。（请参阅下文的「安装共享技能」。）

应用（确认计划后）

1. 初始化 schema

插件在 <plugin>/schemas/ 中提供了 seed schema——该目录位于此技能目录向上两 级，然后进入 schemas/（此技能位于 <plugin>/skills/bm-setup/）。对于编码配置， 请读取 coding-session.md；对于通用配置，请读取 session.md，然后读取 decision.md 和 task.md。

这些 schema 涵盖 Claude 集成直接写入的笔记。生命周期封套不是笔记：bm hook flush 会在本地归档该操作跟踪记录，因此无需初始化投影的会话或工具账本 schema。

对于每个 schema：

• 检查所选项目是否已有该类型的 schema （使用 search_notes 和 metadata_filters={"type": "schema"}，或尝试 read_note("schemas/<name>")）。如果已存在，就跳过——绝不要覆盖用户可能已自定义的 schema。
• 否则，使用 write_note 将其写入 primaryProject（将其作为 project 传入，或者如果它是 external_id UUID，则作为 project_id 传入）：
  • directory="schemas"、note_type="schema"、title = schema 的标题 （Session / Decision / Task）。
  • content = 仅包含 Markdown 正文——即 --- frontmatter 块之后的所有内容（# Session 标题和正文）。
  • metadata = schema 的结构化 frontmatter，使用嵌套字典：entity、 version、完整的 schema 映射，以及 settings（保留其嵌套的 frontmatter，并将枚举值作为 JSON 数组传入，例如 ["open","resumed","closed"]）。
  • 不要将 schema 的 --- frontmatter 放进 content。在云端写入路径中，嵌套的 YAML 会被静默强制转换为字符串 '[object Object]'（basic-memory-cloud#1000），导致 schema/settings 损坏。metadata 参数在本地和云端都能正确往返传递。初始化后，使用 read_note(..., output_format="json", include_frontmatter=true) 验证一篇笔记——schema/settings 必须以嵌套对象而非字符串的形式返回。
• **编码配置：**所选 coding-session.md schema 的 Git 身份字段 （repository、repo_root、cwd、branch、git_sha）按设计为必填字段。 必填且有依据的字段可让编码检查点支持查询，因此应原样初始化此 schema，而不是同时初始化通用 Session schema。

2. 安装共享技能（如果用户选择安装）

首先，避免覆盖源码检出目录。 如果 ./skills 已存在、受 git 跟踪且包含 memory-* 目录，那么你位于技能自己的源码仓库中（例如 basic-memory 本身）——安装会用已发布版本覆盖工作副本。在这种情况下，跳过安装并告知用户技能已作为源码存在；不要运行命令。快速检查：

git ls-files skills/ | grep -q memory- && echo "source repo - skip install"

否则，运行：

npx skills add basicmachines-co/basic-memory/skills -g

-g 会在用户级别（~/.claude/skills/）安装规范的 memory-* 技能， 让每个项目都能使用它们——这是与 OpenClaw 共享的唯一事实来源。插件不会附带副本； 它依赖这套共享技能。如果 npx / skills CLI 不可用，请引导用户参阅顶层的手动安装说明 skills/README.md。

3. 编写设置

根据访谈构建 basicMemory 块：

{
  "basicMemory": {
    "primaryProject": "<chosen>",
    "secondaryProjects": [],
    "captureFolder": "sessions",
    "rememberFolder": "bm-remember",
    "recallTimeframe": "3d",
    "preCompactCapture": "extractive",
    "sessionProfile": "coding",
    "repository": "owner/name",
    "captureEvents": true,
    "placementConventions": "<learned or suggested summary, or null>",
    "teamProjects": {}
  },
  "outputStyle": "basic-memory"
}

明确持久化 sessionProfile。只有在用户确认后，才为 coding 配置持久化 repository——因为 coding_session 架构要求可查询的 Git 身份字段，所以没有仓库标识符的 coding 配置是不完整的。对于 general 配置，省略这两个键的示例值（"sessionProfile": "general"，不含 repository）。

只有在用户选择启用时才包含 outputStyle。询问用户这是团队默认设置（写入/合并到 .claude/settings.json，并建议提交该文件），还是个人设置（.claude/settings.local.json）。合并到任何现有文件中——先读取文件，只添加/替换上述键，并保留其他所有内容。使用紧凑、有效的 JSON。始终将 captureEvents 持久化为 JSON 布尔值。

写入 basicMemory 块也会停止 SessionStart hook 首次运行时的提示——配置存在即表示设置已运行。

4. 冒烟测试连通性

结束前，验证实际能够解析到记忆——这可以在用户还在场时发现项目名称错误、云凭据缺失或引用无法路由等问题并修复。通过它使用的 CLI（basic-memory / bm / uvx --prerelease=allow basic-memory）运行与 SessionStart hook 相同的结构化查询：

• **主项目：**针对 primaryProject 运行 … tool search-notes --type schema --page-size 10——如果是 UUID，使用 --project-id <uuid>；否则使用 --project <ref>。查询应返回你刚刚植入的架构。对于 coding 配置，确认存在 Coding Session 架构。
• 一个共享项目（仅当 secondaryProjects 非空时）：针对第一个引用运行 --type decision --status open 查询。只要查询能正常完成即可——返回 0 results 没问题；报错则表示该引用无法路由。
• **Hook 健康状态：**使用首个可用的 basic-memory、bm 或 uvx --prerelease=allow basic-memory 启动器运行 basic-memory hook status --harness claude --project-dir <project-root>。它必须找到预期的设置，并报告所选项目和捕获状态。在设置摘要中记录共享收件箱深度和上次刷新状态；这些计数包含来自所有受支持运行环境的信封。

如果查询报错，或主项目没有返回任何结果，在结束前说明问题并修正项目引用——不要让下一次会话的简报空空如也。

结束

用几行确认你完成的工作：项目映射、会话配置（以及 coding 配置中已确认的仓库）、已植入的架构与原本已存在的架构、放置位置是从用户处了解的还是由你建议的、冒烟测试结果、是否启用了生命周期事件捕获、共享 hook 收件箱/刷新状态，以及是否启用了输出风格。

然后根据输出风格处理启用方式：

• 已启用输出风格 → 它在会话开始时固定，因此完整的捕获反射行为要到下次会话才会生效。提示用户重启会话（启动一个新的 Claude Code 会话）以启用这些行为。请准确说明，避免让用户误以为“现在什么都用不了”：本次会话中记忆检索已经可用（SessionStart hook 的提示词已运行），PreCompact 检查点现在也能工作——只有主动捕获反射行为需要等待重启。
• 未启用输出风格 → 无需重启；hooks 已经在运行。

最后写上：*"完成——我会从下一条消息开始使用这些内容。随时运行 /basic-memory:bm-status，查看我正在追踪的内容。"