🏛️ @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