🏛️ opencode-mempalace

AI Memory That Actually Works — Project-scoped, persistent memory for OpenCode with zero-config setup.

OpenCode plugin integrating MemPalace lifetime memory system. Unlike other memory solutions, this provides true project-scoped memory with automatic context injection, background mining, and seamless MCP integration.

✨ Why This Plugin?

| Feature | opencode-mempalace | Other Solutions | |---------|-------------------|-----------------| | Project-scoped memory | ✅ Automatic per-workspace | ❌ Global only | | Auto-initialization | ✅ Palace auto-created | ❌ Manual setup | | Context injection | ✅ wakeUp() loads L0+L1 memory | ❌ Manual tool calls | | Background mining | ✅ Idle/threshold/exit triggers | ❌ None or manual | | MCP Tools | ✅ 19 native tools | ❌ CLI only | | Auto-update | ✅ Built-in | ❌ Manual |

🚀 Quick Start

# 1. Install mempalace CLI globally
pip install mempalace

# 2. Add plugin to OpenCode config
# Edit ~/.config/opencode/opencode.jsonc
{
  "plugin": ["opencode-mempalace"]
}

# 3. Open any project folder in OpenCode
# The plugin auto-initializes and starts tracking memory!

🎯 Key Features

1. Project-Scoped Memory (Wings)

Each workspace gets its own isolated memory "wing":

~/projects/web-app      → wing_web-app
~/projects/api-service  → wing_api-service  
~/projects/mobile-app   → wing_mobile-app

Memories never leak between projects. Context is automatically loaded when you switch workspaces.

2. Zero-Config Auto-Initialization

First time opening a project? The plugin automatically:

• Detects if palace exists
• Initializes it in background if needed
• Loads existing context via wakeUp()
• Starts tracking for mining

3. Smart Context Injection

[Session Start] → injects PALACE_PROTOCOL + wakeUp() memory
[Message 2+]    → continues with context aware of previous work  
[Compaction]    → rescues critical memory before context loss

4. Background Auto-Mining

Your conversations are automatically saved:

• Message threshold: Every 15 messages (configurable)
• Session idle: When you stop chatting
• Session deleted: Cleanup trigger
• Process exit: Emergency sync save on Ctrl+C

5. 19 Native MCP Tools

Full MemPalace integration without CLI:

| Tool | Description | |---|---| | mempalace_status | Palace overview | | mempalace_search | Semantic memory search | | mempalace_kg_query | Knowledge graph queries | | mempalace_diary_read/write | Session journaling | | mempalace_add_drawer | Store specific memories | | ...and 14 more |

6. Built-in Auto-Update

Checks NPM registry on session start, auto-installs updates in background. Never miss improvements.

📋 Configuration

// ~/.config/opencode/opencode.jsonc
{
  "plugin": [
    ["opencode-mempalace", {
      "threshold": 20,        // Messages before auto-mining (default: 15)
      "palacePath": "/custom/path",  // Custom palace directory
      "disableAutoLoad": false,       // Skip wakeUp injection
      "disableAutoMining": false,    // Disable background mining
      "disableAutoUpdate": false,     // Disable version checks
      "disableMcp": false            // Skip MCP registration
    }]
  ]
}

Options

| Option | Type | Default | Description | |---|---|---|---| | mcpCommand | string[] | ["python3", "-m", "mempalace.mcp_server"] | Command to start the MCP server | | disableMcp | boolean | false | Skip auto-registering MCP server | | disableProtocol | boolean | false | Skip injecting PALACE_PROTOCOL | | disableAutoLoad | boolean | false | Skip auto-loading context | | disableAutoUpdate | boolean | false | Skip auto-update check | | palacePath | string | ~/.mempalace/palace | Override palace directory | | disableAutoMining | boolean | false | Disable background mining | | threshold | number | 15 | Messages before auto-mining |

🔄 Comparison with option-K/opencode-plugin-mempalace

This plugin is an evolution of the excellent option-K/opencode-plugin-mempalace, adding:

| Addition | Benefit | |----------|---------| | MCP Server Integration | 19 native tools vs CLI-only | | Auto-update mechanism | Self-updating plugin | | Diary tracking | Session journaling with reminders | | Bun ecosystem | Faster builds, no execa dependency | | Security hardening | Path validation, length limits |

What we kept from the original:

• ✅ 3-state initialization (empty/initializing/ready)
• ✅ wakeUp() with L0+L1 memory loading
• ✅ Background mining with StateManager
• ✅ Emergency exit handlers
• ✅ Project-scoped wings
• ✅ AAAK compression support

🧪 Development

# Clone and setup
git clone https://github.com/nguyentamdat/opencode-mempalace
cd opencode-mempalace
bun install

# Build
bun run build

# Test
bun test

# Check types
bun run check

🙏 Credits & Shout Outs

• milla-jovovich/mempalace — The original MemPalace memory system architecture, AAAK dialect, and Python implementation. This plugin is just the OpenCode integration layer.

• option-K/opencode-plugin-mempalace — The pioneering OpenCode plugin that established the patterns for wakeUp, background mining, and 3-state initialization. We ported and extended these concepts.

• OpenCode — The AI terminal that makes plugins like this possible.

• Bun — The fast JavaScript runtime that powers our builds.

📄 License

MIT © nguyentamdat

⭐ Star this repo if you find it useful!
🐛 Report issues — 💡 Suggest features — 🔧 Submit PRs