Add FastMCP Skills Provider + CLI skill loading for Basic Memory skills

[bm-clawd]

Summary

Basic Memory skills (memory-notes, memory-tasks, memory-reflect, etc.) should be discoverable and loadable through multiple access patterns — not just file reads. This would make BM skills first-class citizens across any agent framework.

Motivation

Currently, agents need to know the filesystem path to a SKILL.md and read it into context. This works but is tightly coupled to specific agent frameworks. With FastMCP 3.0 introducing the Skills Provider, there is an opportunity to make BM skills natively available via MCP resources, CLI, and existing agent skill directories — all from the same source files.

Proposal

1. FastMCP Skills Provider (MCP-native discovery)

Since Basic Memory already uses FastMCP, add a SkillsDirectoryProvider to the MCP server that exposes BM skills as skill:// resources:

from fastmcp.server.providers.skills import SkillsDirectoryProvider

# Point at wherever BM ships its skills
mcp.add_provider(SkillsDirectoryProvider(roots=BM_SKILLS_DIR))

This gives any MCP client:

• list_resources() → discovers skill://memory-notes/SKILL.md, skill://memory-tasks/SKILL.md, etc.
• read_resource("skill://memory-notes/SKILL.md") → full skill content injected into context
• Manifest resources for supporting files (schemas, examples, references)

2. CLI-native skill loading

Add a skill subcommand to the basic-memory CLI:

# List available skills
basic-memory skill list

# Dump skill content to stdout (agent execs this, content lands in context)
basic-memory skill load memory-notes

# Load multiple at once
basic-memory skill load memory-notes memory-tasks

This makes skills accessible to any agent that can shell out — Claude Code, Codex, Cursor, or any custom agent. No MCP required.

3. Agent skills directory integration

Skills should also be installable into standard agent skill directories (~/.claude/skills/, ~/.cursor/skills/, etc.) so they are picked up natively by those tools. This is already partially addressed by the basic-memory-skills repo.

Three access paths, one source of truth

Access Pattern	Who Uses It	How
FastMCP Skills Provider	Any MCP client (Claude Desktop, Cursor, etc.)	skill:// resources
CLI basic-memory skill	Any agent with exec/shell access	stdout injection
Agent skills directories	Claude Code, Cursor, OpenClaw, etc.	Native skill scanning

Open Questions

• Where do skills physically live? Inside the basic-memory Python package? Separate repo (basic-memory-skills)? Both (bundled core + extensible)?
• Skill distribution — should basic-memory skill install <name> pull from a registry, or just copy bundled skills into the appropriate agent directory?
• Relationship to existing skills repo — the basic-memory-skills repo already ships skills. How does this integrate?

References

• FastMCP Skills Provider docs
• basic-memory-skills repo
• FastMCP vendor providers already cover Claude, Cursor, Codex, Gemini, etc.

[claude]

Claude finished @bm-clawd's task in 1m 49s —— View job

---

Issue Triage

• Gather context and analyze issue
• Check for duplicate issues
• Classify issue type, priority, complexity
• Apply labels
• Provide triage summary

---

Triage Summary

Type: Feature Request — new functionality to expose Basic Memory skills as first-class citizens across multiple agent frameworks.

Priority: Medium — enhances discoverability and agent interoperability, but no existing functionality is broken.

Components: MCP tools + CLI commands

Complexity: Complex — requires:

• Bundling/organizing skill markdown files within the Python package
• Integrating FastMCP SkillsDirectoryProvider into the MCP server
• Adding a new basic-memory skill CLI subcommand with list and load commands
• Decisions around skill distribution and relationship to the external basic-memory-skills repo

---

Related Issues

• [FEATURE] investigate how Claude skills can be used with Basic Memory #372 (Investigate how Claude skills can be used with Basic Memory) — related but not a duplicate. [FEATURE] investigate how Claude skills can be used with Basic Memory #372 is about investigating the Claude Skills concept, while this issue is a concrete proposal to implement FastMCP Skills Provider and CLI skill loading. These could be worked together.

---

Notes for Implementation

Current State:

• Basic Memory already uses fastmcp>=3.0.1 — the SkillsDirectoryProvider is already available as a dependency
• No existing skill files are bundled in the package; skills live in the external basic-memory-skills repo
• The MCP server (src/basic_memory/mcp/server.py) would need mcp.add_provider(SkillsDirectoryProvider(...)) added to the lifespan/setup
• The CLI (src/basic_memory/cli/commands/) would need a new skill.py command module registered in __init__.py

Open Questions to Resolve Before Implementing:

1. Where do skills live? Should core skills be bundled inside the basic-memory Python package (e.g., src/basic_memory/skills/) or should this only work with a user-configured skills directory?
2. Skill discovery path — what default path should the SkillsDirectoryProvider point to? The bundled package path? A user-configurable path in BasicMemoryConfig?
3. CLI skill load behavior — is stdout injection the right pattern, or should this integrate with the existing tool command?