claude-code

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 general session or schema-backed coding_session checkpoint note to the graph, so the texture of the session survives and the next one can resume from it.
• Deliberate checkpoints (bm-checkpoint skill). On request — "checkpoint this", "wrap up", "hand off" — Claude writes a durable handoff note: the story, verification actually run, decisions, blockers, and the next action. In a coding setup these are schema-backed coding_session notes with required repository, branch, and SHA context, plus typed pull-request context when a PR exists, queryable by structured filters instead of prose search.
• Orient from memory (bm-orient skill). A deliberate mid-session "where do things stand" — reads active tasks, open decisions, and recent checkpoints (repository-scoped for coding setups) and presents an evidence-backed orientation with permalinks.
• Capture decisions (bm-decide skill). Records a durable choice with rationale, alternatives, consequences, and affected work — the deliberate version of the output style's inline decision capture, available whether or not that style is enabled.
• 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.
• Writing standard (bm-writing skill). One user-customizable standard for how Claude writes memory — voice, narrative quality, observations, relations, and git anchors (project, branch, PR, sha) — applied by bm-remember and the capture reflexes.
• Seed schemas. Picoschema definitions for session, decision, and task notes, plus coding_session for coding setups, 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:bm-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:bm-orient	Deliberate orientation — reads active tasks, open decisions, and recent checkpoints from the graph and summarizes where things stand, with permalinks. The mid-session counterpart to the SessionStart brief.
/basic-memory:bm-checkpoint	Deliberate checkpoint — writes a durable handoff note (story, verification, decisions, next action). Coding setups get schema-backed coding_session notes with required Git identity. Also fires when you say "checkpoint this" or "wrap up".
/basic-memory:bm-decide	Capture a durable decision — rationale, alternatives, consequences, affected work — as a type: decision note findable by structured recall. Also fires when you say "record this decision".
/basic-memory:bm-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:bm-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:bm-status	Diagnostic — shows the active project, team read-sources and share targets, capture folders, shared local hook inbox/flush health, recent session checkpoints, and active-task count.
/basic-memory:bm-writing	The writing standard applied whenever Claude writes or substantially revises a note. Not usually invoked directly — edit skills/bm-writing/SKILL.md to change how memory is written.

Requirements

• uv — required: the hooks are PEP 723 scripts executed via uv run --script. Install per platform:
  • macOS: brew install uv (or the curl installer below)
  • Linux/macOS: curl -LsSf https://astral.sh/uv/install.sh | sh
  • Windows: powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
• Basic Memory connected as an MCP server. The hooks resolve their own basic-memory through uv, so no PATH install is required for them.
• Claude Code.

What the hooks execute

The hook scripts are zero-logic PEP 723 uv scripts: uv run --quiet --script resolves basic-memory>=<floor> (pinned in each script's inline metadata) and the script invokes basic-memory hook <event> in-process with the hook JSON on stdin. All behavior lives in the released Python package — versioned, typed, and tested. Setting BM_BIN (a binary path or a quoted launcher string) overrides the uv-managed environment, e.g. for development against a local checkout. Two disclosures:

• Network fetch on first run. uv downloads basic-memory from PyPI at a pinned minimum version (bumped by release tooling); later runs use uv's cache.
• Event capture is on by default. Setting captureEvents: false disables lifecycle-event envelopes. Other values fail closed. Envelopes contain bounded lifecycle metadata and live in a local inbox under your Basic Memory home. Inspect with basic-memory hook status, archive locally with basic-memory hook flush. The lifecycle trace never becomes a graph note.

Every failure path exits 0 — the hooks stay invisible rather than disrupt a session.

Installation

Install the plugin once with Basic Memory and Claude Code on your PATH:

bm install claude-code

This registers the GitHub marketplace and installs basic-memory@basicmachines-co through Claude Code, sparse-checking out only the two paths the plugin needs. Use --dry-run to preview the commands or --yes to skip confirmation. The default Git source uses its default branch, independently of the installed Basic Memory Python version. Hooks require uv as described above.

The install is user-level, so one install covers every project on the machine. Pass --scope project to declare the marketplace and plugin in the repository's .claude/settings.json instead — the way to hand the plugin to a whole team — or --scope local to keep it in untracked local settings. For a local checkout, run bm install claude-code --source /path/to/basic-memory; the source must be the repository root containing .claude-plugin/marketplace.json, and --sparse is omitted because Claude Code accepts it only for Git sources.

Restart Claude Code after installing so it loads the plugin's skills, MCP configuration, and hooks.

Alternatively, run the underlying commands directly:

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:bm-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"
  }
}

The block can also live in your user-level settings. When CLAUDE_CONFIG_DIR is present, its literal value is the user configuration directory and settings.json is read below it. An empty, whitespace, relative, or tilde-prefixed value is preserved exactly, matching Claude Code. When the variable is absent, the user settings path is ~/.claude/settings.json. One user-level block covers every project, with no per-repo setup. Precedence, lowest to highest: user-level settings.json → project settings.json → project settings.local.json, merged per key — so a project that pins its own primaryProject wins over the user-level default. (This mirrors Claude Code's own sources: settings.local.json is project-scoped only, so there is no user-level settings.local.json.) The hooks resolve the project settings from the nearest ancestor directory (including the working directory) whose .claude folder contains a settings.json or settings.local.json, so a mapping in the repo root still applies when Claude starts in a subdirectory.

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
sessionProfile	general	coding makes checkpoints schema-backed coding_session notes with required Git identity
repository	(none)	User-confirmed stable repository identifier (owner/name); required for the coding profile
captureEvents	true	Record bounded lifecycle-event envelopes to the local inbox (see basic-memory hook status / flush). Set the JSON boolean false to disable it; other values fail closed.

The plugin seeds schemas for notes the Claude integration writes directly: decision, task, and the session type relevant to the selected profile. A general setup seeds session; a coding setup (persisted as sessionProfile: "coding" with a user-confirmed repository) seeds coding_session, whose required repository, repo-root, working-directory, branch, and Git SHA frontmatter make checkpoints queryable by structured filters; typed pull-request fields are added when a PR exists. Lifecycle-event envelopes are operational trace rather than knowledge; bm hook flush archives them locally and never creates session or tool-ledger notes.

To customize how Claude writes memory, edit skills/bm-writing/SKILL.md in the plugin source. bm-remember and the output style's capture reflexes apply that shared standard while retaining their own schemas and evidence requirements.

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:bm-remember only ever write to your primaryProject. Nothing lands in a team project automatically.
• Share deliberately — /basic-memory:bm-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:bm-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