Skip to content
This repository was archived by the owner on Feb 15, 2026. It is now read-only.

PLUGIN.md

Latest commit

 

History

History
408 lines (295 loc) · 10.7 KB

PLUGIN.md

File metadata and controls

408 lines (295 loc) · 10.7 KB

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-plugins

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-plugins"
        }
      }
    },
    "installed": ["basic-memory@basicmachines"]
  }
}

Memo Validation with basic-memory-hooks

For consistent, machine-readable memos, integrate with basic-memory-hooks - a validation service that catches LLM formatting inconsistencies and fixes them automatically.

Quick Start

# 1. Clone and install
cd ~/code
gh repo clone basicmachines-co/basic-memory-hooks
cd basic-memory-hooks
uv sync  # or: pip install -e .

# 2. Start the validation server
uv run python -m basic_memory_hooks

# 3. Verify it's running
curl http://localhost:8000/health
# Returns: {"status":"healthy"}

How It Works

When you create memos using /remember, /research, or write notes directly, the validation server:

  1. Validates frontmatter - Ensures title and type exist
  2. Fixes observation format - Converts - fact: to - [fact]
  3. Removes duplicate sections - Merges multiple ## Observations blocks
  4. Validates categories - Checks against allowed observation types
  5. Orders relations - Primary relations before secondary

Example Validation

curl -X POST http://localhost:8000/validate \
  -H "Content-Type: application/json" \
  -d '{
    "title": "My Memo",
    "content": "---\ntitle: My Memo\ntype: memo\n---\n\n# My Memo\n\n## Observations\n\n- [fact] Something learned\n- [decision] Choice made\n- [technique] Approach used"
  }'

Response:

{
  "success": true,
  "content": "...",
  "errors": [],
  "warnings": [],
  "metadata": {"hooks_run": ["validate_frontmatter", "format_observations", ...]}
}

Default Observation Categories

Required Optional
fact insight
decision question
technique idea
requirement
problem
solution

Custom categories can be configured in .basic-memory/format.md.

See the validate-memo skill for complete documentation.

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.

validate-memo

Validates and fixes memo formatting using basic-memory-hooks before saving.

Triggers when:

  • Creating memos via /remember or /research
  • Writing structured notes with observations
  • Content needs format validation

Prerequisites:

  • basic-memory-hooks server running at http://localhost:8000

How it works:

  1. Sends memo content to validation API
  2. Checks against project format configuration
  3. Auto-fixes formatting issues (observation format, duplicates)
  4. Returns validated content or error details

Best for: Ensuring consistent, machine-readable knowledge capture.

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.

PreToolUse: write_note

Before saving a note, prompts validation against the hooks server if running.

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

basic-memory-plugins/
├── .claude-plugin/
│   ├── marketplace.json     # Marketplace manifest
│   └── plugin.json          # Plugin manifest
├── 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/
│   ├── validate-memo/       # NEW: Memo validation
│   └── research/
├── hooks/
│   └── hooks.json           # Hook definitions
├── README.md                # Quick start guide
└── PLUGIN.md                # Full documentation

Related