Help us improve
Share bugs, ideas, or general feedback.
From basic-memory
Configures Basic Memory plugin for a project via a short guided interview, handling project mapping, schema seeding, placement conventions, and capture reflexes.
How this skill is triggered — by the user, by Claude, or both
Slash command
/basic-memory:setup (no arguments — runs an interactive interview)(no arguments — runs an interactive interview)The summary Claude sees in its skill listing — used to decide when to auto-load this skill
Run a short, adaptive interview (~2-3 minutes) and then write the configuration.
Share bugs, ideas, or general feedback.
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.
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):
uv tool install basic-memory (or pip install basic-memory),
version >= 0.19.0.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.
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?"
list_memory_projects() and let them pick. That name becomes
primaryProject.create_memory_project.
~/basic-memory/<name>/; any
connected Basic Memory server can create it.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).
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./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:
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.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.)
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:
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.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"]).--- 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.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.
Build the basicMemory block from the interview:
{
"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.
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):
… 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.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.
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:
End with: "Done — I'll use this from the next message. Run /basic-memory:status
anytime to see what I'm tracking."
npx claudepluginhub basicmachines-co/basic-memory --plugin basic-memoryScaffolds Total Recall memory system: creates memory/registers (people, projects etc.), daily/archive dirs, SCHEMA.md, CLAUDE.local.md working memory, and .gitignore entry.
Integrates sage-memory for persistent knowledge across sessions via MCP tools or file fallback. Automates recall at session/task starts and storage during work.
Captures cross-project learnable patterns (decisions, errors, insights) into a persistent semantic graph via Neural Memory MCP. Auto-recalls context at session start and captures learnings after feature work, debugging, or code review.