https://github.com/basicmachines-co/basic-memory-skills
OpenClaw skills for AI memory management — reflection, defragmentation, and more
https://github.com/basicmachines-co/basic-memory-skills
Last synced: 3 months ago
JSON representation
OpenClaw skills for AI memory management — reflection, defragmentation, and more
- Host: GitHub
- URL: https://github.com/basicmachines-co/basic-memory-skills
- Owner: basicmachines-co
- Created: 2026-02-14T18:57:34.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-03-05T20:57:53.000Z (3 months ago)
- Last Synced: 2026-03-05T23:41:50.391Z (3 months ago)
- Size: 78.1 KB
- Stars: 3
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# basic-memory-skills
Skills for [Basic Memory](https://github.com/basicmachines-co/basic-memory) — teach AI coding agents how to use Basic Memory's MCP tools effectively.
## What Are Skills?
Skills are markdown instruction files (`SKILL.md`) that AI agents load for domain-specific guidance. Each skill contains structured knowledge about *when* and *how* to use specific tools, with examples and best practices.
Basic Memory provides the MCP server — tools like `write_note`, `search_notes`, and `build_context` for managing a local-first knowledge graph. These skills teach agents how to use those tools well: when to create tasks vs. notes, how to structure observations for searchability, when to run schema validation, and more.
## Skills
| Skill | Description | When to use |
|-------|-------------|-------------|
| **memory-tasks** | Structured task tracking that survives context compaction. Creates typed `Task` notes with steps, status, and context. | Multi-step work (3+ steps), anything that might outlast a context window, or after compaction to resume. |
| **memory-schema** | Schema lifecycle management — discover unschemaed notes, infer schemas, create/edit definitions, validate, and detect drift. | When structured note types emerge (Task, Person, Meeting, etc.) and you want consistency. |
| **memory-reflect** | Sleep-time memory reflection. Reviews recent conversations and daily notes, extracts insights, consolidates into long-term memory. Inspired by [sleep-time compute](https://www.letta.com/blog/sleep-time-compute). | Schedule via cron (1-2x daily), trigger from heartbeat, or run on demand. |
| **memory-notes** | How to write well-structured notes — frontmatter, observations with semantic categories, relations with wiki-links, and best practices. | When creating or improving notes, or when you need a reference for the note format. |
| **memory-metadata-search** | Structured metadata search — query notes by custom frontmatter fields using equality, range, array, and nested filters. | When finding notes by status, priority, confidence, or any custom YAML field. |
| **memory-defrag** | Memory defragmentation — split bloated files, merge duplicates, remove stale information, restructure the hierarchy. | Run weekly/biweekly via cron, or on demand when memory feels messy. |
| **memory-lifecycle** | Entity lifecycle management — status transitions through folder-based organization, archiving completed work. Core principle: archive, never delete. | When marking items complete, archiving old entities, or managing folder-based status workflows. |
| **memory-ingest** | Process unstructured external input into structured entities. Parses meeting transcripts, conversation logs, and pasted documents. | When pasting a transcript, conversation log, or external document that should become structured knowledge. |
| **memory-research** | Web research synthesized into Basic Memory entities. Researches a subject, checks for existing knowledge, presents findings, and creates entity notes. | When asked to research a company, person, technology, or topic. |
| **memory-literary-analysis** | Analyze a complete literary work into a structured knowledge graph — characters, themes, chapters, locations, symbols, and literary devices. | Full-text literary analysis, book club companions, teaching resources, or research projects. |
## Basic Memory Cloud
Everything works locally — cloud adds cross-device, team, and production capabilities:
- **Your agent's memory travels with you** — same knowledge graph on laptop, desktop, and hosted environments
- **Team knowledge sharing** — org workspaces let multiple agents and team members build on a shared knowledge base
- **Durable memory for production agents** — persistent memory that survives CI teardowns and container restarts
- **Multi-agent coordination** — multiple agents can read and write to the same graph
Cloud extends local-first — still plain markdown, still yours. Start with a [7-day free trial](https://basicmemory.com) and use code `BMFOSS` for 20% off for 3 months.
## Installation
### Via npx skills (recommended)
Install or update skills using the [Skills CLI](https://github.com/vercel-labs/skills):
```bash
# Install all skills
npx skills add basicmachines-co/basic-memory-skills
# Install a specific skill
npx skills add basicmachines-co/basic-memory-skills --skill memory-tasks
# Install all skills for a specific agent
npx skills add basicmachines-co/basic-memory-skills --agent claude
# List available skills without installing
npx skills add basicmachines-co/basic-memory-skills --list
# Check for updates
npx skills check
# Update installed skills
npx skills update
```
Skills are installed to your agent's skills directory (e.g., `~/.claude/skills/` for Claude Code global, or `.claude/skills/` for project-scoped).
### Claude Desktop (claude.ai)
Claude Desktop loads skills through **Settings > Capabilities**:
1. Clone or download this repository
2. In Claude, go to **Settings > Capabilities** and ensure both **Code execution** and **Skills** are enabled
3. Click **Upload skill** and upload the `SKILL.md` file (or ZIP the skill folder and upload that)
4. Toggle the skill on — Claude will use it automatically when relevant
Repeat for each skill you want. Custom uploaded skills are private to your account.
> **Tip:** Start with **memory-notes** (core note-writing patterns) and add others as needed. You don't need all 9 at once.
See [Using Skills in Claude](https://support.claude.com/en/articles/12512180-using-skills-in-claude) for more details.
### Manual install
Copy skill directories into your agent's skills folder:
```bash
# Claude Code — global
cp -r memory-tasks ~/.claude/skills/
cp -r memory-notes ~/.claude/skills/
# ... etc.
# Claude Code — project-scoped
cp -r memory-tasks .claude/skills/
# Any agent that reads SKILL.md files
cp -r memory-tasks /
```
### Bundled with OpenClaw plugin
All 9 skills are also bundled in the [`@basicmemory/openclaw-basic-memory`](https://github.com/basicmachines-co/openclaw-basic-memory) plugin — no extra install step needed if you use OpenClaw.
## Compatible Agents
These skills work with any AI coding agent that supports the SKILL.md format:
- **Claude Desktop** — upload skill ZIPs via Settings > Capabilities
- **Claude Code** — loads skills from `~/.claude/skills/` or `.claude/skills/`
- **Cursor** — AI-powered coding with skill support
- **Windsurf** — agent-based development with skill loading
- **Any agent** supporting markdown-based skill files
## Development
See [DEVELOPMENT.md](./DEVELOPMENT.md) for testing and contribution details.
## License
MIT