basic-memory-toolkit

Basic Memory Toolkit

A comprehensive Claude Code plugin for managing Basic Memory knowledge bases with quality enforcement, structured workflows, automated validation, and schema-driven note types.

Attribution

This plugin builds on the excellent work from the Basic Memory project by Basic Machines. It cherry-picks and extends patterns from their official repositories:

• basic-memory — The core knowledge management system and MCP server that powers all note operations
• basic-memory-plugins — Official Claude Code plugin; our slash commands and skill structure draw from their patterns
• basic-memory-skills — Official skill library; our skills were inspired by and extend their approach

This toolkit adds development-focused features (two-tier validation, schema types for bugs/decisions/patterns, spec-driven development workflows) on top of their foundation.

Features

• 13 specialized skills for note creation, editing, searching, consolidation, validation, and knowledge capture
• 8 slash commands for quick workflows: /remember, /continue, /organize, /research, /dev-session, /capture-decision, /validate-project, /doctor
• 8 schema definitions for development-focused note types (bug-report, design-decision, code-pattern, etc.)
• Memory organizer agent for autonomous multi-project knowledge management
• 6 automated hooks for session management, validation, quality checks, and context preservation
• Two-tier validation — instant inline checks (PreToolUse) + thorough CLI validators (batch)
• Polyglot setup script (Linux/macOS/Windows) for prerequisite installation and MCP registration
• Memory rules seed data for bootstrapping quality standards

Prerequisites

The plugin requires the basic-memory MCP server as an external prerequisite (no longer bundled — see docs/MIGRATION.md if upgrading from v2.x).

Requirement	Purpose
uv	Runs the basic-memory MCP server via uvx
basic-memory	The MCP server itself (auto-installed on first uvx invocation)
Claude Code CLI	Registers the MCP server with claude mcp add

The setup script (Step 2 below) installs uv and registers the MCP server for you. See docs/INSTALL.md for full details, manual install steps, and MCP scope configuration.

Installation

Step 1: Install the plugin

Option A — From GitHub marketplace (recommended)

claude plugin marketplace add https://github.com/ZivBA/basic-memory-toolkit.git basic-memory-toolkit

Option B — Local plugin directory (development)

claude --plugin-dir /path/to/basic-memory-toolkit

Option C — Copy to project

cp -r basic-memory-toolkit /your/project/.claude-plugin/

Step 2: Install the prerequisite

If you installed from the CLI (Option A or B without launching Claude yet), run the setup script directly from the plugin directory before starting Claude Code:

# Linux / macOS / WSL / Git Bash
./scripts/setup-prerequisites.cmd

# Windows
scripts\setup-prerequisites.cmd

If you installed the plugin from inside an active Claude Code session, quit Claude Code first, then run the setup script. Do not use /reload-plugins — the script registers an MCP server via claude mcp add, which is best applied with no live session holding config state.

The script detects uv, installs it via the official Astral installer if missing, smoke-tests basic-memory, prompts for MCP registration scope, and registers the server. After it completes, start (or restart) Claude Code.

Step 3: Verify

Inside Claude Code, run /basic-memory-toolkit:doctor for a full diagnostic report.

First Run

On first install, the plugin displays a welcome message with setup steps. On version updates from v2.x, it shows a migration notice (see docs/MIGRATION.md). On routine version bumps it shows a brief "updated" notice. On steady-state sessions (stored version matches plugin.json) the welcome/migration messages are silent — only the standard project-selection prompt fires.

Reconciliation state is stored in ${CLAUDE_PLUGIN_DATA}/version (typically ~/.claude/plugins/data/basic-memory-toolkit/version). To force the welcome/migration message to fire again, delete that file and restart Claude Code. The legacy v2.x flag at ~/.claude/basic-memory-toolkit.initialized is automatically cleaned up on first v3.0.0+ session.

Step 1: Import Seed Rules (Recommended)