🏛️ @kevincojean/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.

🍴 Fork Rationale

This project is a fork of the original opencode-plugin-mempalace, which laid the groundwork for integrating MemPalace with OpenCode. The original plugin worked well with Claude Code, which stores sessions in markdown files, but OpenCode uses SQLite databases for session storage. This fork adds full SQLite support, enabling reliable session data access and background mining in OpenCode environments. It continues under new stewardship to keep the project active and maintained.

✨ Why This Plugin?

| Feature | @kevincojean/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 | | Multi-backend mining | ✅ SQLite + Markdown | ❌ Local files only |

🚀 Quick Start

# 1. Install mempalace CLI globally
pip install mempalace

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

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

Note: OpenCode resolves npm packages automatically when listed in the plugin array. No manual npm install needed.

🎯 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.

7. SQLite Backend (opencode.db)

Mining reads directly from OpenCode's SQLite database (opencode.db), providing faster and more reliable session data access compared to markdown file parsing. The dataSource option lets you control which backend to use:

• "auto" (default): Try SQLite first, fall back to markdown
• "sqlite": Force SQLite only
• "markdown": Force markdown file parsing

📋 Configuration

// ~/.config/opencode/opencode.jsonc
{
  "plugin": [
    ["@kevincojean/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
      "disableMiningNotification": false,  // Disable mining trigger toast
      "dataSource": "auto"                // Session data source: 'auto', 'sqlite', 'markdown'
    }]
  ]
}

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 | | disableMiningNotification | boolean | false | Disable mining trigger notification toast | | threshold | number | 15 | Messages before auto-mining | | dataSource | "auto" \| "sqlite" \| "markdown" | "auto" | Session data source for mining (auto tries SQLite first, falls back to markdown) |

🔄 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/kevincojean/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 © kevincojean

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