mirror of
https://github.com/basicmachines-co/basic-memory
synced 2026-06-21 13:47:35 +00:00
feat: Complete plugin with marketplace, commands, and hooks
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 <url> - 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 <noreply@anthropic.com> Signed-off-by: phernandez <paul@basicmachines.co>
This commit is contained in:
phernandez
@@ -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"]
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -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 <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
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 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)
|
||||
|
||||
@@ -0,0 +1,39 @@
|
||||
---
|
||||
description: Build context from a Basic Memory URL
|
||||
argument-hint: <memory://url> [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
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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.
|
||||
@@ -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."
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user