setup

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Basic Memory setup

Basic Memory 配置流程

Run a short, adaptive interview (~2-3 minutes) and then write the configuration. Be conversational and skip questions whose answer is already obvious from context (e.g. if

list_memory_projects

shows a single local project and no cloud workspaces, don't ask about cloud/teams — just confirm). Suggest a sensible default for every question so the user can accept with one word. Don't do any writes until the interview is done and you've confirmed the plan.

运行一个简短的自适应引导流程（约2-3分钟），然后写入配置。保持对话式风格，跳过那些从上下文可明显推断出答案的问题（例如，如果

list_memory_projects

显示只有一个本地项目且无云工作区，则无需询问云/团队相关问题——直接确认即可）。为每个问题提供合理的默认选项，用户只需一个词即可确认。在引导流程完成并确认配置方案前，不要执行任何写入操作。

Prerequisite check

前置检查

First confirm the Basic Memory MCP server is connected — call

list_memory_projects

. If that tool isn't available or errors, Basic Memory isn't wired into Claude Code yet. Stop and walk the user through it first (everything below depends on it):

Install it:

uv tool install basic-memory

(or

pip install basic-memory

), version

>= 0.19.0

Connect it:
```
claude mcp add basic-memory -- uvx basic-memory mcp
```
, then restart the session so the MCP server loads.

Re-check

list_memory_projects

before continuing — don't start the interview until it succeeds.

首先确认Basic Memory MCP服务器已连接——调用

list_memory_projects

。如果该工具不可用或报错，说明Basic Memory尚未接入Claude Code。请先引导用户完成连接步骤（后续所有操作均依赖于此）：

安装插件：

uv tool install basic-memory

（或

pip install basic-memory

），版本要求

>= 0.19.0

。

连接插件：
```
claude mcp add basic-memory -- uvx basic-memory mcp
```
，然后重启会话以加载MCP服务器。

继续前请重新检查

list_memory_projects

——确保调用成功后再启动引导流程。

Interview

引导流程

Ask only what you can't infer. Cover:

Focus / how you'll use it. "What will this project mostly be — code/dev, research, writing, knowledge capture, planning, or a mix?" This answer is load-bearing, not small talk: it drives the folder structure you suggest (step 4) and is stored so the SessionStart brief can surface it, keeping capture matched to the use-case. Don't let it evaporate — if you infer it from context instead of asking, still say the use-case you assumed and the structure it implies, and let the user correct it in one word.
Project mapping. "Do you already have a Basic Memory project for this, or should I create one?"
- Existing → show
```
list_memory_projects()
```
  and let them pick. That name becomes
```
primaryProject
```
  .
- New → propose a name (default: this repo's directory name) and create it with
```
create_memory_project
```
  .
  - Local project (default): path defaults to
```
~/basic-memory/<name>/
```
    ; any connected Basic Memory server can create it.
  - Cloud project (the user wants capture in a cloud workspace): pass the
```
workspace
```
    selector (a slug from
```
list_workspaces
```
    ) and a cloud-style path like
```
/<name>
```
    , and create it with a cloud-connected MCP server. A purely local server (
```
uvx basic-memory mcp
```
    ) treats the path as a local directory and fails to create it (e.g. read-only
```
/
```
    ). When both a local and a cloud server are connected, route creation and the schema seeding through the cloud one, and pin
```
primaryProject
```
    to the new project's
```
external_id
```
    UUID (collision-proof across workspaces).
Cloud / teams (skip if there are no extra workspaces). Run
```
list_workspaces
```
. If the user belongs to more than one workspace, they likely have a team workspace alongside their personal/default one. Use
```
list_memory_projects
```
to see the projects in each (note: project names collide across workspaces, so always use the workspace-qualified name, e.g.
```
my-team-2/notes
```
, or the
```
external_id
```
UUID — never a bare name).
- Read from the team (recommended): ask which team projects to pull into the session brief for recall. Store their qualified names in
```
secondaryProjects
```
  . These are read-only — recall reads across them; nothing is written to them. Cap: the SessionStart brief reads only the first 6 shared projects per session (a latency/output bound), in list order. If the user wants more than six, order the most relevant first and tell them the rest are configured but not read each session.
- Share target (optional): if the user wants a place to publish notes to the team via
```
/basic-memory:share
```
  , add it to
```
teamProjects
```
  as
```
"<qualified-name>": { "promoteFolder": "shared" }
```
  . Sharing is always a manual gesture — auto-capture never writes to a team project.
Keep
```
primaryProject
```
a project the user owns for their own capture; team projects are for reading and deliberate sharing only.
Placement — learn or suggest (depends on the project's state). The goal is a short
```
placementConventions
```
string (3-6 lines) telling you where new notes go. How you get it depends on whether the project already has notes:
- Existing project with notes → learn. Inspect it:
```
list_directory
```
  for the folder layout, sample a few notes per folder (and, where a folder holds recurring typed notes, you may run
```
schema_infer
```
  to see their shape). Summarize the real conventions — folder-by-topic layout, naming style, the observation categories they favor. Infer from their actual notes; don't impose.
- New or empty project → suggest (there's nothing to learn yet). Propose a light structure that fits the focus from step 1 — 3-5 optional top-level folders, no deep taxonomy — and be explicit that it's a starting point, not a scaffold: notes work fine without it and structure can stay emergent. Don't create empty folders; folders appear as notes land in them. Let the user edit or decline in one word. Either way, keep it short and store the result as
```
placementConventions
```
  . The SessionStart brief surfaces it (alongside
```
captureFolder
```
  ), so this is what makes your captures land where the user expects — without it, placement is guesswork.
Schemas. "I'll add schemas for session checkpoints, decisions, and tasks so I can find them precisely later — okay?" (See "Seed the schemas" below.)
How active should I be? (output style) "Want me to proactively capture — search the graph before recalling, write material decisions as typed notes, and cite permalinks? Or keep it quiet (just the session brief, the PreCompact checkpoint, and
```
/basic-memory:remember
```
on demand)?" Enabling it sets
```
outputStyle: "basic-memory"
```
. Default to enabled; leave it off for a recall-only, low-noise setup. (This is the single knob for how proactive the assistant is — the hooks always run regardless.)
Shared skills (optional, default yes). "Want the full Basic Memory toolkit — the shared
```
memory-*
```
skills (
```
memory-notes
```
,
```
memory-tasks
```
,
```
memory-research
```
,
```
memory-schema
```
,
```
memory-defrag
```
, …)? I can install them alongside this plugin." These are the canonical, framework-agnostic skills (the same set OpenClaw bundles). This plugin ships only the Claude-Code-specific glue and pulls the shared set on demand — it doesn't vendor its own copies. (See "Install the shared skills" below.)

仅询问无法从上下文推断的问题，需覆盖以下内容：

使用场景/用途。“这个项目主要用于什么场景——代码开发、研究、写作、知识捕获、规划，还是混合场景？”这个答案至关重要，并非闲聊：它将决定你建议的文件夹结构（步骤4），并会被存储以便SessionStart提示调用，确保捕获内容与使用场景匹配。不要忽略这一步——如果从上下文推断出场景，仍需告知用户你假设的场景及其对应的结构，并允许用户用一个词进行修正。
项目映射。“你是否已为此项目创建过Basic Memory项目，还是需要我新建一个？”
- 已有项目 → 调用
```
list_memory_projects()
```
  并让用户选择。所选名称将设为
```
primaryProject
```
  。
- 新建项目 → 提议一个名称（默认：当前仓库的目录名），并通过
```
create_memory_project
```
  创建。
  - 本地项目（默认）：路径默认为
```
~/basic-memory/<name>/
```
    ；任何已连接的Basic Memory服务器均可创建。
  - 云项目（用户希望在云工作区中捕获内容）：传入
```
workspace
```
    选择器（来自
```
list_workspaces
```
    的slug）和类似
```
/<name>
```
    的云风格路径，并通过云连接的MCP服务器创建。纯本地服务器（
```
uvx basic-memory mcp
```
    ）会将路径视为本地目录，创建可能失败（例如只读的
```
/
```
    目录）。当同时连接本地和云服务器时，通过云服务器完成项目创建和schema初始化，并将
```
primaryProject
```
    绑定到新项目的
```
external_id
```
    UUID（跨工作区无冲突）。
云/团队协作（若无额外工作区则跳过）。调用
```
list_workspaces
```
。如果用户属于多个工作区，他们可能拥有一个团队工作区和个人/默认工作区。使用
```
list_memory_projects
```
查看每个工作区中的项目（注意：项目名称在不同工作区可能重复，因此始终使用工作区限定名称，例如
```
my-team-2/notes
```
，或
```
external_id
```
UUID——切勿使用裸名称）。
- 读取团队项目（推荐）：询问要将哪些团队项目纳入会话提示以进行召回。将其限定名称存储在
```
secondaryProjects
```
  中。这些项目为只读——召回时会跨项目读取，但不会向其写入任何内容。上限：SessionStart提示每次会话仅读取前6个共享项目（受延迟/输出限制），按列表顺序排列。如果用户选择超过6个，需将最相关的项目排在前面，并告知用户其余项目已配置但不会在每次会话中读取。
- 共享目标（可选）：如果用户希望通过
```
/basic-memory:share
```
  将笔记发布到团队，可将其添加到
```
teamProjects
```
  中，格式为
```
"<qualified-name>": { "promoteFolder": "shared" }
```
  。共享始终是手动操作——自动捕获绝不会向团队项目写入内容。
请将
```
primaryProject
```
设为用户拥有的个人捕获项目；团队项目仅用于读取和主动共享。
存储规范——学习或建议（取决于项目状态）。目标是生成一个简短的
```
placementConventions
```
字符串（3-6行），告知新笔记的存储位置。获取方式取决于项目是否已有笔记：
- 已有笔记的项目 → 学习。检查项目结构：调用
```
list_directory
```
  查看文件夹布局，每个文件夹抽样查看几个笔记（如果文件夹包含重复类型的笔记，可调用
```
schema_infer
```
  查看其结构）。总结实际的存储规范——按主题划分的文件夹布局、命名风格、偏好的分类方式。根据用户的实际笔记进行推断，不要强加规范。
- 新项目或空项目 → 建议（尚无内容可学习）。根据步骤1确定的使用场景，提出一个轻量化的结构——3-5个可选顶级文件夹，无需深层分类体系，并明确说明这只是起点，并非固定框架：笔记无需结构也能正常使用，结构可逐步形成。不要创建空文件夹；文件夹会在笔记存入时自动生成。允许用户用一个词编辑或拒绝建议。无论哪种方式，都要保持内容简短，并将结果存储为
```
placementConventions
```
  。SessionStart提示会调用该内容（连同
```
captureFolder
```
  ），这是确保捕获内容存放在用户预期位置的关键——若无此配置，存储位置将只能靠猜测。
Schema设置。“我将添加会话检查点、决策和任务的schema，以便后续精准查找——可以吗？”（请参阅下方“初始化schema”部分。）
主动程度？（输出风格）。“你希望我主动捕获内容——召回前搜索图谱、将重要决策写入类型化笔记并引用永久链接？还是保持静默（仅提供会话提示、PreCompact检查点，以及按需调用
```
/basic-memory:remember
```
）？”启用主动捕获会设置
```
outputStyle: "basic-memory"
```
。默认启用；若仅需召回功能、低干扰配置则关闭。（这是控制助手主动程度的唯一开关——钩子始终会运行。）
共享技能（可选，默认启用）。“你需要完整的Basic Memory工具包——共享的
```
memory-*
```
技能（
```
memory-notes
```
、
```
memory-tasks
```
、
```
memory-research
```
、
```
memory-schema
```
、
```
memory-defrag
```
等）吗？我可以将它们与该插件一同安装。”这些是标准的、框架无关的技能（与OpenClaw捆绑的技能集相同）。该插件仅包含Claude-Code特定的适配代码，会按需调用共享技能集——不会自带副本。（请参阅下方“安装共享技能”部分。）

Apply (after confirming the plan)

应用配置（确认方案后）

1. Seed the schemas

1. 初始化schema

The plugin ships seed schemas at

<plugin>/schemas/

— that's two directories up from this skill's directory, then
schemas/
(this skill is at

<plugin>/skills/setup/

). Read

session.md

decision.md

, and

task.md

there.

For each one:

Check whether the chosen project already has a schema for that type (
```
search_notes
```
with
```
metadata_filters={"type": "schema"}
```
, or try
```
read_note("schemas/<name>")
```
). If it exists, skip it — never overwrite a schema the user may have customized.
Otherwise write it with
```
write_note
```
, routed to
```
primaryProject
```
(pass it as
```
project
```
, or as
```
project_id
```
if it's an
```
external_id
```
UUID):
- ```
directory="schemas"
```
  ,
```
note_type="schema"
```
  ,
```
title
```
  = the schema's title (Session / Decision / Task).
- ```
content
```
  = the markdown body only — everything after the
```
---
```
  frontmatter block (the
```
# Session
```
  heading and the prose).
- ```
metadata
```
  = the schema's structured frontmatter as a nested dict:
```
entity
```
  ,
```
version
```
  , the full
```
schema
```
  map, and
```
settings
```
  (keep its nested
```
frontmatter
```
  , and pass enum values as JSON arrays, e.g.
```
["open","resumed","closed"]
```
  ).
- Do not put the schema's
```
---
```
  frontmatter inside
```
content
```
  . On the cloud write path that nested YAML is silently coerced to the string
```
'[object Object]'
```
  (basic-memory-cloud#1000), corrupting
```
schema
```
  /
```
settings
```
  . The
```
metadata
```
  param round-trips correctly on both local and cloud. After seeding, verify one note with
```
read_note(..., output_format="json", include_frontmatter=true)
```
  —
```
schema
```
  /
```
settings
```
  must come back as nested objects, not strings.

插件在

<plugin>/schemas/

目录下提供了初始schema——路径为当前技能目录向上两级，然后进入
schemas/
（当前技能位于

<plugin>/skills/setup/

）。读取其中的

session.md

、

decision.md

和

task.md

。

针对每个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
```
  必须以嵌套对象形式返回，而非字符串。

2. Install the shared skills (if the user opted in)

2. 安装共享技能（若用户选择启用）

First, guard against clobbering a source checkout. If

./skills

already exists, is tracked in git, and holds

memory-*

directories, you're inside the skills' own source repo (e.g.

basic-memory

itself) — the install would overwrite the working copy with published versions. In that case skip the install and tell the user the skills are already present as source; don't run the command. Quick check:

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

Otherwise, run from the project root:

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

This installs the canonical

memory-*

skills into the user's skills directory — the single source of truth, shared with OpenClaw. The plugin does not vendor copies; it relies on this shared set. If

npx

/ the

skills

CLI isn't available, point the user at the manual install in the top-level

skills/README.md

首先防止覆盖源码检出。如果

./skills

已存在、被git跟踪，且包含

memory-*

目录，则当前处于技能的源码仓库中（例如

basic-memory

本身）——安装操作会用发布版本覆盖工作副本。这种情况下跳过安装，告知用户技能已作为源码存在；不要运行安装命令。快速检查命令：

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

否则，从项目根目录运行：

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

此命令会将标准的

memory-*

技能安装到用户的技能目录中——这是与OpenClaw共享的唯一可信源。该插件不会自带副本；依赖此共享技能集。如果

npx

skills

CLI不可用，请引导用户查看顶级目录

skills/README.md

中的手动安装说明。

3. Write settings

3. 写入设置

Build the

basicMemory

block from the interview:

json

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

Only include

outputStyle

if the user opted in. Ask whether this is a team default (write/merge into

.claude/settings.json

, suggest committing it) or personal (

.claude/settings.local.json

). Merge into any existing file — read it, add/replace only the keys above, preserve everything else. Use compact, valid JSON.

Writing the

basicMemory

block is also what stops the SessionStart hook's first-run nudge — the config's presence is the signal that setup has run.

根据引导流程构建

basicMemory

配置块：

json

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

仅当用户选择启用时才包含

outputStyle

。询问用户这是团队默认配置（写入/合并到

.claude/settings.json

，建议提交到git）还是个人配置（

.claude/settings.local.json

）。合并到现有文件中——读取文件内容，仅添加/替换上述键，保留其他所有内容。使用紧凑、有效的JSON格式。

写入

basicMemory

配置块也会停止SessionStart钩子的首次运行提示——配置的存在是已完成设置的信号。

4. Smoke-test the wiring

4. 连通性冒烟测试

Before you close, prove recall actually resolves — this catches a misnamed project, missing cloud credentials, or a ref that doesn't route, while the user is still here to fix it. Run the same structured query the SessionStart hook runs, via the CLI it uses (

basic-memory

bm

uvx basic-memory

Primary:

… tool search-notes --type schema --page-size 5

against

primaryProject

— use

--project-id <uuid>

for a UUID,

--project <ref>

otherwise. It should return the three schemas you just seeded.

One shared project (only if
```
secondaryProjects
```
is non-empty): a
```
--type decision --status open
```
query against the first ref. It just needs to return cleanly —
```
0 results
```
is fine; an error means the ref doesn't route.

If a query errors, or the primary returns nothing, surface it and fix the project ref before closing — don't let the next session's brief come up empty.

结束前，请验证召回功能是否正常——这可以在用户在场时发现项目名称错误、缺失云凭证或路由引用无效等问题。运行SessionStart钩子使用的结构化查询，通过其使用的CLI（

basic-memory

bm

uvx basic-memory

）：

主项目：针对
```
primaryProject
```
运行
```
… tool search-notes --type schema --page-size 5
```
——若为UUID则使用
```
--project-id <uuid>
```
，否则使用
```
--project <ref>
```
。应返回刚才初始化的三个schema。
一个共享项目（仅当
```
secondaryProjects
```
非空时）：针对第一个引用运行
```
--type decision --status open
```
查询。只需返回结果正常即可——
```
0 results
```
没问题；报错意味着引用路由无效。

如果查询报错，或主项目返回空结果，请告知用户并修复项目引用后再结束——不要让下一次会话的提示内容为空。

Close

结束

Confirm what you did in a few lines: the project mapping, which schemas were seeded vs. already present, whether placement was learned or suggested, the smoke-test result, and whether the output style is on.

Then handle activation based on the output style:

Output style enabled → it's fixed at session start, so the full capture reflexes only take effect next session. Prompt the user to restart the session (start a new Claude Code session) to activate them. Be precise so it doesn't read as "nothing works yet": recall is already live this session (the SessionStart hook's prompt ran), and the PreCompact checkpoint works now too — only the proactive-capture reflexes wait for the restart.
Output style off → no restart needed; the hooks already run.

End with: "Done — I'll use this from the next message. Run
/basic-memory:status
anytime to see what I'm tracking."

用几句话确认已完成的操作：项目映射情况、哪些schema是新初始化的/已存在、存储规范是学习而来还是建议的、冒烟测试结果，以及输出风格是否启用。

然后根据输出风格处理激活：

输出风格已启用 → 该设置在会话启动时生效，因此完整的捕获触发功能需等到下一次会话。提示用户重启会话（启动新的Claude Code会话）以激活功能。请明确说明，避免用户误解为“当前无法使用”：本次会话中召回功能已生效（SessionStart钩子的提示已运行），PreCompact检查点也已可用——仅主动捕获触发功能需等待重启。
输出风格已关闭 → 无需重启；钩子已在运行。

最后告知用户：“完成——从下一条消息开始我将使用此配置。随时运行

/basic-memory:status

查看我正在跟踪的内容。”",