/bm-setup

name: bm-setup
description: Set up the Basic Memory plugin for this project — a short guided interview that configures the project mapping, seeds note schemas, learns or suggests placement conventions, and enables capture reflexes. Use when the user runs /basic-memory:bm-setup, says "set up basic memory", or asks to configure/bootstrap the plugin.
argument-hint: (no arguments — runs an interactive interview)

Basic Memory setup

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.

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):

1. Install it: `uv tool install basic-memory --prerelease=allow` (or `pip install basic-memory`), version `>= 0.19.0`. Keep `--prerelease=allow` with uv: published releases pin a FastMCP pre-release, and without the flag uv silently installs an older Basic Memory release. 2. Connect it: `claude mcp add basic-memory -- uvx --prerelease=allow 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.

Interview

Ask only what you can't infer. Cover:

1. **Focus / how you'll use it.** "What will this project mostly be — code/dev, research, writing, knowledge capture, planning, or a mix?" This answer drives the folder structure you suggest (step 4) and is stored so the SessionStart brief can surface it. If you infer it instead of asking, state the use-case you assumed and the structure it implies so the user can correct it in one word.

A code/dev answer makes this a **coding setup** (`sessionProfile: "coding"`): verify the directory is inside a Git repository, resolve a stable `repository` identifier such as `owner/name` from the origin remote or GitHub CLI, show it to the user, and ask for confirmation. Do not guess when the remote is missing or ambiguous, and do not infer `coding` merely because the current directory is a Git checkout — for mixed use, ask whether this repository should capture Git and pull-request context. The coding profile seeds the Coding Session schema so deliberate checkpoints carry required, queryable Git identity (repository, branch, SHA, and working directory), plus typed pull-request fields when a PR exists.

2. **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 --prerelease=allow 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).

3. **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:bm-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.

4. **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