basicmachines-co-basic-memory/claude-code-plugin/PLUGIN.md

Basic Memory Plugin for Claude Code

This plugin provides skills, commands, and hooks for working with Basic Memory - a local-first knowledge management system built on the Model Context Protocol (MCP).

Prerequisites

You need the Basic Memory MCP server running. Install it via:

# Install basic-memory
pip install basic-memory

# Or with pipx
pipx install basic-memory

Then add it to your Claude Code MCP configuration.

Installation

Add the Marketplace

/plugin marketplace add basicmachines-co/basic-memory/claude-code-plugin

Install the Plugin

/plugin install basic-memory@basicmachines

Or via Repository Settings

Add to your .claude/settings.json:

{
  "plugins": {
    "extraKnownMarketplaces": {
      "basicmachines": {
        "source": {
          "source": "github",
          "repo": "basicmachines-co/basic-memory",
          "path": "claude-code-plugin"
        }
      }
    },
    "installed": ["basic-memory@basicmachines"]
  }
}

---

Slash Commands

User-invoked commands for explicit interaction with Basic Memory.

/remember [title] [folder]

Capture insights, decisions, or learnings from the current conversation.

/remember "FastAPI Async Pattern"
/remember "Auth Decision" decisions

Creates a structured note with:

• Context from the conversation
• Observations with [decision], [insight], [pattern] categories
• Relations linking to related concepts

/continue [topic]

Resume previous work by building context from Basic Memory.

/continue postgres migration
/continue SPEC-24
/continue

If no topic is provided, shows recent activity and asks what to dive into.

/context <memory://url> [depth] [timeframe]

Build context from a specific memory:// URL.

/context memory://SPEC-24
/context memory://architecture/* 3 2weeks

/recent [timeframe] [project]

Show recent activity in Basic Memory.

/recent
/recent 1week
/recent today specs

/organize [action] [project]

Organize and maintain your knowledge graph.

/organize                    # Quick health check
/organize orphans            # Find unlinked notes
/organize duplicates         # Find similar notes
/organize relations "Note"   # Suggest links for a note
/organize tags               # Review tag consistency

Actions:

• health - Overview of knowledge base status (default)
• orphans - Find notes with no relations
• duplicates - Find overlapping notes
• relations - Suggest connections
• tags - Review tag consistency

/research <topic> [folder]

Research a topic and save a structured report to Basic Memory.

/research MCP protocol
/research "database migrations"
/research "auth options" decisions

Produces a report with:

• Summary and key findings
• Analysis and recommendations
• Sources and related notes
• Saved to research/ folder by default

---

Skills

Model-invoked capabilities that Claude uses automatically based on context.

knowledge-capture

Automatically captures insights, decisions, and learnings into structured notes.

Triggers when:

• Important decisions are made
• Technical insights are discovered
• Problems are solved
• Design trade-offs are discussed

continue-conversation

Resumes previous work by building context from the knowledge graph.

Triggers when:

• Starting a new session
• User mentions previous work ("continue with...", "back to...")
• Need context about ongoing projects

spec-driven-development

Guides implementation based on specifications stored in Basic Memory.

Triggers when:

• Implementing a feature defined by a spec
• Creating new specifications
• Reviewing implementation against criteria

edit-note

Interactively edit notes using MCP tools in a conversational workflow.

Triggers when:

• User wants to edit, update, or modify a note
• User asks to change specific content in a note
• User wants to add observations or relations

How it works:

1. Fetches the note via MCP
2. Shows current content
3. Applies edits using edit_note operations (append, prepend, find_replace, replace_section)
4. Shows the updated result

Best for: Cloud users or when you want conversational editing.

edit-note-local

Edit notes directly as local markdown files with automatic sync.

Triggers when:

• User has local Basic Memory installation
• User wants to make substantial file edits
• User prefers working with full file content

How it works:

1. Finds the note's file path via MCP
2. Uses Claude Code's Read/Edit/Write tools on the actual file
3. Basic Memory's sync --watch picks up changes automatically

Best for: Local users who want full file access and git integration.

knowledge-organize

Help organize, link, and maintain the knowledge graph.

Triggers when:

• User wants to organize their notes
• User asks about orphan or unlinked notes
• User wants to find connections between notes
• User mentions duplicates or similar notes
• User asks for help with folder organization

Capabilities:

• Find orphan notes - Identify notes with no relations
• Suggest relations - Propose meaningful links between notes
• Identify duplicates - Find notes covering similar topics
• Folder organization - Review and suggest folder structure
• Tag consistency - Normalize and improve tagging
• Create index notes - Generate hub notes linking related topics
• Enrich sparse notes - Suggest observations and structure

Best for: Periodic knowledge base maintenance and improving discoverability.

research

Research topics thoroughly and produce structured reports saved to Basic Memory.

Triggers when:

• User asks to research or investigate something
• User wants to understand a concept or technology
• User needs context before making a decision
• Phrases like "research", "look into", "explore", "investigate"

What it produces:

• Structured report with summary, findings, and analysis
• Recommendations when applicable
• Links to sources and related notes
• Saved to research/ folder

Best for: Building knowledge base through investigation and documentation.

---

Hooks

Automated behaviors that enhance the Basic Memory workflow.

PostToolUse: write_note

Confirms when notes are saved to Basic Memory.

Stop

After significant conversations, suggests using /remember to capture valuable insights (only when genuinely useful).

---

MCP Tools Used

This plugin leverages Basic Memory's MCP tools:

Tool	Purpose
write_note	Create/update markdown notes
read_note	Read notes by title or permalink
search_notes	Full-text search across content
build_context	Navigate knowledge graph via memory:// URLs
recent_activity	Get recently updated information
edit_note	Incrementally update notes

---

Plugin Structure

claude-code-plugin/
├── .claude-plugin/
│   ├── plugin.json          # Plugin manifest
│   └── marketplace.json     # Self-hosted marketplace
├── commands/
│   ├── remember.md          # /remember command
│   ├── continue.md          # /continue command
│   ├── context.md           # /context command
│   ├── recent.md            # /recent command
│   ├── organize.md          # /organize command
│   └── research.md          # /research command
├── skills/
│   ├── knowledge-capture/
│   ├── continue-conversation/
│   ├── spec-driven-development/
│   ├── edit-note/
│   ├── edit-note-local/
│   ├── knowledge-organize/
│   └── research/
├── hooks/
│   └── hooks.json           # Hook definitions
├── README.md                # Quick start guide
└── PLUGIN.md                # Full documentation

---

Related

• Basic Memory Documentation
• Basic Memory GitHub
• Model Context Protocol
• Claude Code Plugins