This plugin provides skills and hooks for working with Basic Memory — a local-first knowledge management system built on the Model Context Protocol (MCP).
It uses Claude Code's plugin format (skills and hooks bundled into an installable marketplace) and only works with Claude Code.
Looking for framework-agnostic skills? See
basic-memory-skills—SKILL.mdfiles that work in Claude Code, Claude Desktop, and other MCP-compatible agents. The hooks in this plugin are Claude Code-specific and aren't available there.
You need the Basic Memory MCP server running. Install it via:
# Install basic-memory
pip install basic-memory
# Or with pipx
pipx install basic-memoryThen add it to your Claude Code MCP configuration.
/plugin marketplace add basicmachines-co/basic-memory-plugins
/plugin install basic-memory@basicmachines-co
Add to your .claude/settings.json:
{
"plugins": {
"extraKnownMarketplaces": {
"basicmachines-co": {
"source": {
"source": "github",
"repo": "basicmachines-co/basic-memory-plugins"
}
}
},
"installed": ["basic-memory@basicmachines-co"]
}
}The plugin reads project conventions from a unified config file. Without one, it falls back to sensible built-in defaults. You can adopt the config gradually as you discover what you want to standardize.
| Scope | Location | Format |
|---|---|---|
| Project | A note titled basic-memory at the project root |
Basic Memory note (read via MCP) |
| Global | ~/.basic-memory/basic-memory.md |
Filesystem markdown file |
The config file uses H2 sections for categories and H3 sub-sections for project-specific overrides. Bare content under an H2 is the default; H3 sub-sections override it for a specific project.
# Basic Memory config
## Projects
- work: default project for daily work
- personal: personal notes and reflections
- research: long-form research notes
## Placements
- Place into existing folders by topic match
- Never create new top-level folders without asking
- Match the project's existing naming convention
### research
- Long-form notes go in `papers/`
- Quick references go in `refs/`
## Formats
- Required frontmatter: title, type, date
- Observation categories: fact, decision, technique, problem, solution
## Schemas
### work
person:
- name
- email
- role| Section | Scope | Purpose |
|---|---|---|
## Projects |
Global only | Routing rules — when to use which project |
## Placements |
Project or global | Folder conventions for new notes |
## Formats |
Project or global | Frontmatter and observation conventions |
## Schemas |
Project or global | Note type definitions |
Other H2 sections are treated as user notes and ignored.
For each section the plugin needs:
- Project's
basic-memorynote → if the section exists, use it - Global
~/.basic-memory/basic-memory.md→ look for### <project>first, then bare content under the H2 - Built-in defaults
Section-level fallback means a project file can override one section while inheriting others from global.
For an existing project with established conventions, ask Claude to generate a starter basic-memory.md based on what's already in the project:
"Look at my
<project-name>project structure and generate a starterbasic-memorynote for it. Inspect the folder layout and existing notes to infer placement and format conventions."
Claude will:
- Inspect the project tree (
list_directory) and sample notes from each folder - Infer naming conventions, depth patterns, and organizational structure
- Draft a
basic-memorynote with## Placementspopulated and other sections as commented placeholders - Show you the draft for review before writing
This is a one-time conversational pattern — no slash command required.
Model-invoked capabilities that Claude uses automatically based on context.
Decides which folder a new note belongs in. Runs automatically before every Basic Memory write_note call via a PreToolUse hook with matcher mcp__.*__write_note (catches local, cloud, and claude.ai connector variants).
Triggers when:
- About to call any MCP basic-memory
write_notetool - Manually invoked when planning a write
How it works:
- Reads project and global config (
basic-memory.md) — extracts## Placementsrules - Short-circuits at the first definitive answer:
- Config rule applies → use it
- Tree match obvious → use it
- Search for related notes → use as a placement signal
- Asks the user if placement remains ambiguous
Best for: Keeping notes organized according to project conventions without per-write instruction.
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
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
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:
- Fetches the note via MCP
- Shows current content
- Applies edits using
edit_noteoperations (append, prepend, find_replace, replace_section) - Shows the updated result
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 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 (or whereverplacementdirects)
Best for: Building knowledge base through investigation and documentation.
Automated behaviors that enhance the Basic Memory workflow.
Advisory reminder before saving a note. Injects context that prompts the model to run the placement skill (if it hasn't already for this write). The hook returns permissionDecision: allow unconditionally — it never blocks the write — so the placement decision is made by the skill + model rather than by hook approval. Matcher is mcp__.*__write_note, so it catches any MCP basic-memory variant (local install, cloud, claude.ai connector).
Confirms when notes are saved to Basic Memory. Same mcp__.*__write_note matcher.
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 |
list_directory |
Inspect project folder structure |
build_context |
Navigate knowledge graph via memory:// URLs |
recent_activity |
Get recently updated information |
edit_note |
Incrementally update notes |
basic-memory-plugins/
├── .claude-plugin/
│ ├── marketplace.json # Marketplace manifest
│ └── plugin.json # Plugin manifest
├── skills/
│ ├── placement/
│ ├── knowledge-capture/
│ ├── continue-conversation/
│ ├── edit-note/
│ ├── knowledge-organize/
│ └── research/
├── hooks/
│ └── hooks.json # Hook definitions
├── agents/
│ └── basic-memory-manager.md
├── README.md # Quick start guide
└── PLUGIN.md # Full documentation