Integrations and Plugins
Relevant source files
- .claude-plugin/marketplace.json
- CHANGELOG.md
- integrations/hermes/MONKEYPATCH.md
- integrations/hermes/README.md
- integrations/hermes/__init__.py
- integrations/hermes/plugin.yaml
- integrations/hermes/tests/test_child_env.py
- integrations/hermes/tests/test_commands.py
- integrations/openclaw/commands/skills.ts
- integrations/openclaw/openclaw.plugin.json
- integrations/openclaw/package.json
- integrations/openclaw/scripts/fetch-skills.ts
- plugins/claude-code/.claude-plugin/marketplace.json
- plugins/claude-code/.claude-plugin/plugin.json
- plugins/claude-code/CHANGELOG.md
- plugins/claude-code/DESIGN.md
- plugins/claude-code/README.md
- plugins/claude-code/output-styles/basic-memory.md
- plugins/claude-code/settings.example.json
- plugins/claude-code/skills/bm-decide/SKILL.md
- plugins/claude-code/skills/bm-orient/SKILL.md
- plugins/claude-code/skills/bm-remember/SKILL.md
- plugins/claude-code/skills/bm-setup/SKILL.md
- plugins/claude-code/skills/bm-share/SKILL.md
- plugins/claude-code/skills/bm-status/SKILL.md
- plugins/codex/.codex-plugin/plugin.json
- pyproject.toml
- scripts/validate_claude_plugin.py
- server.json
- skills/README.md
- skills/memory-onboarding/SKILL.md
- skills/memory-onboarding/evals/evals.json
- skills/memory-onboarding/references/assistant-setup.md
- skills/memory-onboarding/references/conventions.md
- skills/memory-onboarding/references/domain-playbooks.md
- src/basic_memory/__init__.py
This section provides an overview of how Basic Memory integrates with external AI agents and coding environments. The monorepo contains specialized packages that bridge the gap between an agent's ephemeral "working memory" and Basic Memory's durable, local-first knowledge graph.
Basic Memory follows a "use both" philosophy: agents maintain their own immediate operational context (like Claude's MEMORY.md), while Basic Memory provides persistent, cross-project organizational infrastructure for decisions, research, and long-term tasks plugins/claude-code/README.md5-10
Integration Landscape
The codebase organizes integrations into three primary categories:
- IDE-Specific Plugins: Deep integrations for environments like Claude Code plugins/claude-code/.claude-plugin/plugin.json1-9 and Codex plugins/codex/.codex-plugin/plugin.json1-4
- Agent Frameworks: Providers for autonomous agent hosts like Hermes integrations/hermes/__init__.py1-6 and OpenClaw integrations/openclaw/package.json1-10
- Skills System: Framework-agnostic workflow definitions based on
SKILL.mdthat can be installed into any compatible agent plugins/claude-code/README.md14-15
System Integration Map
The following diagram illustrates how the various integration packages communicate with the core Basic Memory services through the Model Context Protocol (MCP) and the bm hook harness.
Integration Architecture Flow
Sources: plugins/claude-code/README.md81-89 integrations/hermes/__init__.py7-12 plugins/claude-code/CHANGELOG.md95-104 CHANGELOG.md107-117
Claude Code Plugin
The Claude Code plugin acts as a "memory bridge" between Claude's working memory and the durable knowledge graph. It utilizes a zero-logic hook architecture where PEP 723 uv scripts invoke the core bm hook command plugins/claude-code/README.md81-89
- Session Briefing: The
SessionStarthook queries Basic Memory for active tasks and recent work to brief Claude at the start of a session plugins/claude-code/README.md19-21 - Compaction Checkpoint: The
PreCompacthook writes asessionorcoding_sessionnote to the graph before the context window compacts plugins/claude-code/README.md22-25 - Slash Commands: Provides namespaced commands under
/basic-memory:*for setup, orientation, and status plugins/claude-code/README.md58-68 - Interactive Setup: The
bm-setupskill runs a guided interview to map projects and seed schemas plugins/claude-code/skills/bm-setup/SKILL.md9-14
For details, see Claude Code Plugin.
Sources: plugins/claude-code/README.md1-108 scripts/validate_claude_plugin.py24-40 plugins/claude-code/skills/bm-setup/SKILL.md1-53 plugins/claude-code/DESIGN.md1-82
Hermes and OpenClaw Integrations
Integrations for agent frameworks like Hermes and OpenClaw utilize a provider-based pattern to wrap the Basic Memory MCP server.
- Hermes Provider: Implements the
BasicMemoryProviderwhich manages a_BmMcpActorthread to hold a session open across the agent's lifetime integrations/hermes/__init__.py7-12 It maps Hermes-side tools likebm_searchto the coresearch_notesMCP tool integrations/hermes/__init__.py69-80 - OpenClaw Integration: A TypeScript-based plugin providing local-first knowledge graph capabilities to the OpenClaw agent host, utilizing shared skills integrations/openclaw/package.json1-10
- Codex Plugin: A Codex-native bridge for durable engineering context, using the same shared skills (orient, checkpoint, decide) as other integrations. It uses
hooks/session_start.pyandhooks/pre_compact.pyasuvshims CHANGELOG.md121-123
For details, see Hermes and OpenClaw Integrations.
Sources: integrations/hermes/__init__.py1-40 integrations/hermes/MONKEYPATCH.md1-54 CHANGELOG.md118-123
Skills System
The Skills system provides a set of framework-agnostic, SKILL.md-based workflows. These are designed to be "portable intelligence" that can be added to any agent that supports the Skills specification.
- Core Skills: Includes
bm-setupfor configuration,bm-checkpointfor durable handoffs, andbm-decidefor capturing engineering decisions scripts/validate_claude_plugin.py31-40 - Writing Standard: The
bm-writingskill provides a user-customizable standard for the voice and narrative quality of notes plugins/claude-code/README.md43-46 - Seed Schemas: Picoschema definitions (e.g.,
session.md,coding-session.md,task.md) ensure that notes written by skills are structured and findable by metadata filters scripts/validate_claude_plugin.py27-29 - Shared Standard: The
bm-writingstandard is shared across Claude Code and Codex to ensure consistency in the semantic layer plugins/claude-code/CHANGELOG.md21-26
For details, see Skills System.
Sources: plugins/claude-code/CHANGELOG.md11-72 plugins/claude-code/skills/bm-remember/SKILL.md1-55 plugins/claude-code/output-styles/basic-memory.md47-59 CHANGELOG.md124-126
Entity and Tool Association
The following table bridges the "Natural Language" concepts used in integrations with the specific code entities that implement them.
Sources: scripts/validate_claude_plugin.py24-40 integrations/hermes/__init__.py7-12 plugins/claude-code/settings.example.json1-19 CHANGELOG.md83-117