From a70b3558385bace0c1c66111bf804ee70a9dca59 Mon Sep 17 00:00:00 2001 From: phernandez Date: Fri, 28 Nov 2025 13:11:11 -0600 Subject: [PATCH] feat: Complete plugin with marketplace, commands, and hooks MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add full plugin infrastructure for distribution: Marketplace: - Add marketplace.json for self-hosting at basicmachines-co/basic-memory - Users can add via: /plugin marketplace add basicmachines-co/basic-memory Slash Commands: - /remember [title] - Capture insights to Basic Memory - /continue [topic] - Resume previous work with context - /context - Build context from memory:// URLs - /recent [timeframe] - Show recent activity Hooks: - PostToolUse: Confirm when notes are saved - Stop: Suggest /remember for valuable conversations Updated PLUGIN.md with comprehensive documentation. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Signed-off-by: phernandez --- .claude-plugin/marketplace.json | 23 +++++ PLUGIN.md | 155 +++++++++++++++++++++++++------- commands/context.md | 39 ++++++++ commands/continue.md | 46 ++++++++++ commands/recent.md | 40 +++++++++ commands/remember.md | 43 +++++++++ hooks/hooks.json | 26 ++++++ 7 files changed, 341 insertions(+), 31 deletions(-) create mode 100644 .claude-plugin/marketplace.json create mode 100644 commands/context.md create mode 100644 commands/continue.md create mode 100644 commands/recent.md create mode 100644 commands/remember.md create mode 100644 hooks/hooks.json diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json new file mode 100644 index 00000000..6561af5b --- /dev/null +++ b/.claude-plugin/marketplace.json @@ -0,0 +1,23 @@ +{ + "name": "basicmachines", + "owner": { + "name": "Basic Machines", + "email": "hello@basicmachines.co" + }, + "metadata": { + "description": "Official plugins from Basic Machines for knowledge management and AI-assisted development", + "version": "0.1.0" + }, + "plugins": [ + { + "name": "basic-memory", + "source": ".", + "description": "Skills, commands, and hooks for Basic Memory MCP - capture knowledge, continue conversations, and follow spec-driven development", + "version": "0.1.0", + "author": { + "name": "Basic Machines" + }, + "keywords": ["memory", "knowledge", "mcp", "specs", "context"] + } + ] +} diff --git a/PLUGIN.md b/PLUGIN.md index ed869044..7910a58c 100644 --- a/PLUGIN.md +++ b/PLUGIN.md @@ -1,6 +1,6 @@ # Basic Memory Plugin for Claude Code -This plugin provides Claude Code skills for working with [Basic Memory](https://basicmemory.io) - a local-first knowledge management system built on the Model Context Protocol (MCP). +This plugin provides skills, commands, and hooks for working with [Basic Memory](https://basicmemory.io) - a local-first knowledge management system built on the Model Context Protocol (MCP). ## Prerequisites @@ -18,30 +18,98 @@ Then add it to your Claude Code MCP configuration. ## Installation -### Via Plugin Command +### Add the Marketplace + +``` +/plugin marketplace add basicmachines-co/basic-memory +``` + +### Install the Plugin ``` /plugin install basic-memory@basicmachines ``` -### Via Repository Settings +### Or via Repository Settings Add to your `.claude/settings.json`: ```json { "plugins": { - "marketplaces": ["basicmachines"], + "extraKnownMarketplaces": { + "basicmachines": { + "source": { + "source": "github", + "repo": "basicmachines-co/basic-memory" + } + } + }, "installed": ["basic-memory@basicmachines"] } } ``` -## Skills Included +--- + +## 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 [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 +``` + +--- + +## Skills + +Model-invoked capabilities that Claude uses automatically based on context. ### knowledge-capture -Automatically capture insights, decisions, and learnings from conversations into structured Basic Memory notes. +Automatically captures insights, decisions, and learnings into structured notes. **Triggers when:** - Important decisions are made @@ -49,56 +117,81 @@ Automatically capture insights, decisions, and learnings from conversations into - Problems are solved - Design trade-offs are discussed -**What it does:** -- Creates structured notes with observations and relations -- Uses appropriate categories (`[decision]`, `[insight]`, `[pattern]`, etc.) -- Links to related knowledge in the graph - ### continue-conversation -Resume previous work by building context from the Basic Memory knowledge graph. +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 -**What it does:** -- Uses `build_context` with memory:// URLs -- Checks `recent_activity` to see what's changed -- Presents relevant context for seamless continuation - ### spec-driven-development -Guide implementation based on specifications stored in Basic Memory. +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 -**What it does:** -- Follows the SPEC-1 process (Create → Discuss → Implement → Validate → Document) -- Updates spec progress as work completes -- Maintains living documentation with checklists +--- -## How Skills Work +## Hooks -Unlike slash commands (user-invoked), skills are **model-invoked** - Claude automatically decides when to use them based on conversation context. You don't need to explicitly call them. +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 -These skills leverage Basic Memory's MCP tools: +This plugin leverages Basic Memory's MCP tools: -- `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 +| 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/ +├── .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 +├── skills/ +│ ├── knowledge-capture/ +│ ├── continue-conversation/ +│ └── spec-driven-development/ +├── hooks/ +│ └── hooks.json # Hook definitions +└── PLUGIN.md # This file +``` + +--- ## Related - [Basic Memory Documentation](https://docs.basicmemory.io) - [Basic Memory GitHub](https://github.com/basicmachines-co/basic-memory) - [Model Context Protocol](https://modelcontextprotocol.io) +- [Claude Code Plugins](https://code.claude.com/docs/en/plugins) diff --git a/commands/context.md b/commands/context.md new file mode 100644 index 00000000..c56f168b --- /dev/null +++ b/commands/context.md @@ -0,0 +1,39 @@ +--- +description: Build context from a Basic Memory URL +argument-hint: [depth] [timeframe] +allowed-tools: mcp__basic-memory__build_context, mcp__basic-memory__read_note +--- + +# Context + +Build context from a Basic Memory memory:// URL. + +## Arguments + +- `$1` - Memory URL (e.g., `memory://topic`, `memory://folder/*`, `memory://SPEC-24`) +- `$2` - Depth of relation traversal (optional, default: 2) +- `$3` - Timeframe for recent changes (optional, default: "7d") + +## Your Task + +Navigate the knowledge graph and build comprehensive context. + +1. **Build context** using `mcp__basic-memory__build_context`: + - url: "$1" + - depth: $2 or 2 + - timeframe: "$3" or "7d" + +2. **Present the context**: + - Main note content + - Related notes found via relations + - Recent changes within timeframe + - Key observations and decisions + +3. **Read additional notes** if needed for more detail. + +## Memory URL Formats + +- `memory://note-title` - Single note by title +- `memory://folder/*` - All notes in a folder +- `memory://SPEC-*` - Pattern matching +- `memory://specs/SPEC-24` - Note in specific project folder diff --git a/commands/continue.md b/commands/continue.md new file mode 100644 index 00000000..047db10e --- /dev/null +++ b/commands/continue.md @@ -0,0 +1,46 @@ +--- +description: Resume previous work from Basic Memory context +argument-hint: [topic] +allowed-tools: mcp__basic-memory__build_context, mcp__basic-memory__recent_activity, mcp__basic-memory__search_notes, mcp__basic-memory__read_note +--- + +# Continue + +Resume previous work by building context from Basic Memory. + +## Arguments + +- `$ARGUMENTS` - Topic, note title, or search terms to find previous context + +## Your Task + +Build context to continue previous work seamlessly. + +1. **Find relevant context**: + + If a specific topic is provided ("$ARGUMENTS"): + - Search for matching notes: `mcp__basic-memory__search_notes` + - Build context from matches: `mcp__basic-memory__build_context` + - Read key notes for details: `mcp__basic-memory__read_note` + + If no topic provided: + - Get recent activity: `mcp__basic-memory__recent_activity` with timeframe "3d" + - Present what's been happening + - Ask which topic to dive into + +2. **Present context**: + - Summarize current state of the work + - Highlight recent changes or progress + - List open items or next steps + - Show related context from the knowledge graph + +3. **Be ready to continue**: + - Understand what was done before + - Know what needs to happen next + - Have relevant context loaded + +## Tips + +- Use `memory://topic` URL format with `build_context` +- Check multiple projects if needed (main, specs) +- Follow relations to find connected knowledge diff --git a/commands/recent.md b/commands/recent.md new file mode 100644 index 00000000..1be014e6 --- /dev/null +++ b/commands/recent.md @@ -0,0 +1,40 @@ +--- +description: Show recent activity in Basic Memory +argument-hint: [timeframe] [project] +allowed-tools: mcp__basic-memory__recent_activity, mcp__basic-memory__read_note +--- + +# Recent + +Show recent activity in Basic Memory. + +## Arguments + +- `$1` - Timeframe (optional): "today", "1d", "3d", "1 week", "2 weeks" (default: "3d") +- `$2` - Project (optional): "main", "specs", etc. + +## Your Task + +Show what's been happening in Basic Memory recently. + +1. **Get recent activity** using `mcp__basic-memory__recent_activity`: + - timeframe: "$1" or "3d" + - project: "$2" or check all projects + +2. **Present activity**: + - List recently modified notes + - Group by type or folder if helpful + - Highlight key changes + - Show dates of modifications + +3. **Offer to dive deeper**: + - Ask if user wants to read any specific notes + - Suggest continuing work on active items + +## Timeframe Examples + +- `today` - Just today +- `1d` or `yesterday` - Last 24 hours +- `3d` - Last 3 days +- `1 week` - Last week +- `2 weeks` - Last 2 weeks diff --git a/commands/remember.md b/commands/remember.md new file mode 100644 index 00000000..1e6d42e9 --- /dev/null +++ b/commands/remember.md @@ -0,0 +1,43 @@ +--- +description: Capture insights, decisions, or learnings to Basic Memory +argument-hint: [title] [optional: folder] +allowed-tools: mcp__basic-memory__write_note, mcp__basic-memory__search_notes +--- + +# Remember + +Capture what we just discussed into a Basic Memory note. + +## Arguments + +- `$1` - Title for the note (required) +- `$2` - Folder to save in (optional, defaults to "notes") + +## Your Task + +Create a structured note capturing the key insights from our conversation. + +1. **Analyze the conversation** for: + - Decisions made + - Insights discovered + - Problems solved + - Patterns identified + - Trade-offs discussed + +2. **Structure the note** with: + - Clear title: "$1" (or generate one if not provided) + - Context section explaining the situation + - Main content with key points + - Observations using `[category]` format: + - `[decision]` - Choices made + - `[insight]` - Understanding gained + - `[pattern]` - Reusable approaches + - `[learning]` - Lessons learned + - Relations to link related concepts with `[[WikiLinks]]` + +3. **Save using** `mcp__basic-memory__write_note`: + - folder: "$2" or "notes" + - Include relevant tags + - Project: use "main" unless user specifies otherwise + +4. **Confirm** what was captured and where it was saved. diff --git a/hooks/hooks.json b/hooks/hooks.json new file mode 100644 index 00000000..edde6010 --- /dev/null +++ b/hooks/hooks.json @@ -0,0 +1,26 @@ +{ + "hooks": { + "PostToolUse": [ + { + "matcher": "mcp__basic-memory__write_note", + "hooks": [ + { + "type": "command", + "command": "echo '✓ Note saved to Basic Memory'" + } + ] + } + ], + "Stop": [ + { + "matcher": "*", + "hooks": [ + { + "type": "prompt", + "prompt": "If this conversation contained valuable insights, decisions, or learnings that should be preserved, suggest using `/remember [title]` to capture them in Basic Memory. Only suggest this if there's genuinely valuable content worth preserving - don't suggest for trivial interactions." + } + ] + } + ] + } +}