basicmachines-co-basic-memory/plugins/claude-code/README.md

Basic Memory for Claude Code

The bridge between Claude's working memory and Basic Memory's durable knowledge graph.

Claude Code now keeps its own auto-memory — fast, in-context notes Claude writes to itself. Basic Memory is the other half: a searchable, portable, semantic graph of markdown files you and Claude both own. This plugin connects the two so you get the documented "use both" setup automatically: Claude starts each session briefed from the graph, and checkpoints the session back to it before the context window compacts.

This package lives in the canonical basic-memory repository under plugins/claude-code/ and only works with Claude Code. For framework-agnostic skills that work in any MCP agent, see the top-level skills/ directory.

What it does

• Session briefing (SessionStart hook). When a session begins, the plugin queries Basic Memory for your active tasks and recent work and puts a short brief in front of Claude — so you start where you left off instead of cold.
• Compaction checkpoint (PreCompact hook). Right before Claude Code compacts the context window, the plugin writes a type: session checkpoint note to the graph, so the texture of the session survives and the next one can resume from it.
• Capture reflexes (output style). An opt-in output style teaches Claude to search the graph before answering recall questions, capture real decisions as typed decision notes, and cite permalinks.
• Seed schemas. Picoschema definitions for session, decision, and task notes, so the stuff the plugin writes is structured and findable by search_notes metadata filters — recall is precise, not fuzzy.

The full design and rationale live in DESIGN.md.

Commands

Plugin skills are namespaced under the plugin name:

Command	What it does
/basic-memory:setup	One-time guided setup — maps the project to a Basic Memory project, seeds the note schemas, installs the shared memory-* skills, optionally learns your conventions, and turns on the capture reflexes. Run this first.
/basic-memory:remember <text>	Quick capture — saves the text to the bm-remember folder with a manual-capture tag. Also fires when you say "remember that…".
/basic-memory:share <note>	Promote a personal note to a configured team project, with attribution and confirmation. The deliberate way to write to a shared workspace.
/basic-memory:status	Diagnostic — shows the active project, team read-sources and share targets, capture folders, output-style state, recent session checkpoints, and active-task count.

Requirements

• Basic Memory >= 0.19.0 connected as an MCP server. uv tool install basic-memory is recommended (it puts a basic-memory binary on PATH, which the hooks call directly). A uvx basic-memory mcp-only setup also works — the hooks fall back to uvx/uv when no binary is on PATH.
• Claude Code.

Installation

claude plugin marketplace add basicmachines-co/basic-memory --sparse .claude-plugin plugins/claude-code
claude plugin install basic-memory@basicmachines-co

Configuration

The fastest path is /basic-memory:setup — a ~2-minute interview that writes the config, seeds the schemas, and turns on the capture reflexes. The SessionStart hook nudges you toward it on first run.

To configure by hand instead: the hooks work out of the box against your default Basic Memory project — no config required. To pin a specific project (recommended, and required for the PreCompact checkpoint to write), add a basicMemory block to your project's .claude/settings.json. Copy settings.example.json and set primaryProject:

{
  "basicMemory": {
    "primaryProject": "my-project",
    "captureFolder": "sessions"
  }
}

To enable the capture reflexes, also set "outputStyle": "basic-memory" in your settings (or select it via /config).

Key	Default	What it does
primaryProject	(default project)	Where briefs read from and checkpoints write to
captureFolder	sessions	Folder for PreCompact checkpoint notes
recallTimeframe	3d	Recency window for the session brief
recallPrompt	(built-in)	The instruction appended to the brief
preCompactCapture	extractive	How checkpoints are produced

See DESIGN.md for the complete configuration schema, the Claude-Code-project ↔ Basic-Memory-project mapping, and team-workspace behavior.

Teams

If you're on Basic Memory Cloud with a team workspace, the plugin reads team context into your session brief and gives you a deliberate way to publish back — without ever auto-writing to the shared graph.

• Read across — add team projects to secondaryProjects. SessionStart pulls their open decisions into your brief (in parallel, read-only), so you start oriented on what the team has decided.
• Capture stays personal — session checkpoints and /basic-memory:remember only ever write to your primaryProject. Nothing lands in a team project automatically.
• Share deliberately — /basic-memory:share copies a chosen note into a teamProjects target (with attribution and a confirmation step). That's the only path to a shared write.

Because project names repeat across workspaces, team refs must be workspace-qualified (my-team/notes) or external_id UUIDs — /basic-memory:setup fills these in for you from list_workspaces.

Documentation

• Why combine Basic Memory with Claude's built-in memory — the value, the personas, the use cases.
• Getting started — a ~5-minute walkthrough from install to a working memory loop.
• Architecture — how it works, flow by flow, with diagrams.
• DESIGN.md — design rationale, decisions, and roadmap.

Development

From the monorepo root:

just package-check-claude-code

From this directory:

just check

just check validates the manifests, hooks, output style, and seed schemas, then runs claude plugin validate . --strict.

License

MIT