budgie-mcp

Budgie Memory MCP Server — Connects AI coding agents (Claude Code, OpenCode, and other MCP clients) to Budgie Memory.

Version

4.2.0 — Multi-platform support: Claude Code + OpenCode with automatic CLI detection.

Quick Start

Installation

# Global (recommended)
npm install -g budgie-mcp

# Or npx (no install needed)
npx budgie-mcp

Usage

With Claude Code

Add to your Claude Code MCP config (~/.claude.json or ~/.claude/settings.json):

{
  "mcpServers": {
    "budgie-memory": {
      "command": "budgie-mcp"
      // or "npx", "-y", "budgie-mcp"
    }
  }
}

With OpenCode

Add to your OpenCode config (~/.config/opencode/opencode.json):

{
  "mcp": {
    "budgie-memory": {
      "type": "local",
      "command": ["npx", "-y", "budgie-mcp"],
      "enabled": true
    }
  }
}

Install Integration Files

The package includes integration files (skills, hooks, instructions) for supported AI coding agents:

# Install integration files (auto-detects installed agents)
budgie-mcp install
# or
npx budgie-mcp install

The installer will:

1. Detect installed agents (Claude Code CLI, OpenCode)
2. Install platform-specific files for each detected agent

Claude Code Integration

• Skills (9 files): ~/.claude/commands/skills/
  • budgie-architecture, budgie-remember, budgie-search, budgie-setup, budgie-stats, budgie-reindex
  • (Deprecated: budgie-briefing, budgie-configs, budgie-context, budgie-decisions, budgie-save-config)
• Hooks (2 files): ~/.claude/hooks/
  • budgie-session-start.sh, budgie-session-end.sh
• Instructions: ~/.claude/budgie-memory.md

OpenCode Integration

• Skills (6 files): ~/.config/opencode/skills/*/SKILL.md
  • Each skill is converted to OpenCode format with YAML frontmatter
  • Skills are available via the skill tool
• MCP Configuration: Automatically added to ~/.config/opencode/opencode.jsonc

Requirements

• Budgie Memory daemon must be running on http://127.0.0.1:7432
  • Start with: budgie-memory (daemon mode)
  • Or set BUDGIE_MEMORY_URL environment variable if running on a different port

MCP Tools

Read Tools

| Tool | Description | |------|-------------| | budgie_search | Semantic vector search with scoring | | budgie_list | Metadata-based paginated list (no embedding) | | budgie_get | Fetch a single memory by UUID | | budgie_stats | Storage statistics (counts, types, disk usage) |

Context Tools

| Tool | Description | |------|-------------| | budgie_project_context | Project summary (synthesis, decisions, recent items) | | budgie_decision_trail | Chronological decisions on a topic | | budgie_types | List all valid memory types |

Write Tools

| Tool | Description | |------|-------------| | budgie_ingest | Write a new memory | | budgie_update | Update an existing memory | | budgie_forget | Soft-delete a memory |

Execution Tools

| Tool | Description | |------|-------------| | budgie_run_task | Trigger a named task (synthesis, classification, etc.) |

Development

# Install dependencies
npm install

# Build TypeScript
npm run build

# Watch mode
npm run dev

# Run locally
npm start

Architecture

┌─────────────────┐     stdio      ┌──────────────────────┐
│  Claude Code    │◄──────────────►│  budgie-mcp (npm)    │
│  (MCP client)   │                │  + @modelcontext     │
└─────────────────┘                │    /mcp/sdk          │
                                   └──────────┬───────────┘
                                              │ HTTP
                                              ▼
                                   ┌──────────────────────┐
                                   │  budgie-memory       │
                                   │  (daemon, :7432)     │
                                   └──────────────────────┘

Key design decision: The MCP server is now a lightweight Node.js package that delegates all heavy lifting (storage, embeddings, synthesis) to the budgie-memory daemon via REST API. This makes deployment and versioning much simpler.

Troubleshooting

"Budgie Memory daemon is not running"

Start the daemon:

budgie-memory

Or check if it's running:

curl http://127.0.0.1:7432/health

MCP server not appearing in Claude Code

Check the MCP logs in Claude Code settings. Look for:

• "budgie-mcp" in the server list
• Error messages in the connection log

Tools return errors

1. Check budgie-memory is running: budgie-memory status
2. Check authentication: budgie-memory requires valid auth via budgie-service
3. Check logs: ~/.budgie/memory/logs/

Version History

• 4.0.1 — Documentation updates, package name simplified
• 4.0.0 — Standalone npm package, uses REST API
• 3.x — Embedded in budgie-memory Rust binary (deprecated)

License

MIT