opencode-mempalace-persistence

Community plugin — not officially maintained by the MemPalace team. Fully open source, ~200 lines of TypeScript.

An OpenCode plugin that automatically saves every conversation to MemPalace and uses stored memory to provide better, context-aware responses. Real-time, zero cron, zero external scripts.

How it works in 3 seconds

| Without plugin | With plugin | |---|---| | Every session starts from scratch | The model knows who you are and what you've done | | You repeat context each time | Memory is automatic | | Model starts from scratch each time | Memory persists across sessions |

The plugin injects relevant memories from MemPalace into every prompt (via experimental.chat.messages.transform), and saves every response back to MemPalace. A perfect feedback loop.

Installation

1. Plugin (saves conversations)

{
  "plugin": ["opencode-mempalace-persistence"]
}

Add this line to your ~/.config/opencode/opencode.json and restart OpenCode.

2. Identity (who you are)

Create ~/.mempalace/identity.txt:

I am [name], a [role]. I work with [technologies]. My main projects are [projects].

This file is loaded by the plugin — no need to add it to instructions in opencode.json.

3. MemPalace (if not already installed)

# Install (requires mempalace>=3.3.5 for HNSW corruption fix)
uv tool install "mempalace>=3.3.5"
# or
pipx install "mempalace>=3.3.5"

# Create palace
mempalace init ~/opencode-memory

# Configure MCP
mempalace mcp

The mempalace mcp command gives you the exact MCP setup string for your configuration.

4. Memory injection (recommended)

The plugin automatically injects your identity + relevant memories from MemPalace into every prompt. No model discipline required.

Create ~/.mempalace/plugin-config.json:

{
  "autoInjectContext": true
}

Do NOT put this in opencode.json — OpenCode's schema validation rejects unknown keys. The plugin reads its config from ~/.mempalace/plugin-config.json instead.

When enabled:

• First message: Injects your identity from ~/.mempalace/identity.txt
• Every message: Runs mempalace search and injects relevant results

AGENTS.md for this mode

Create ~/.config/opencode/AGENTS.md:

# Memory & Knowledge instructions

## CRITICAL: You MUST follow these steps BEFORE every response.

### Step 1 — Query Knowledge Graph
Call `mempalace_mempalace_kg_query` for entity "user". Then filter the returned facts — keep only those whose text contains keywords from the user's question, so irrelevant facts are excluded.

### Step 2 — Record Knowledge Graph facts

After responding, if you discovered any new facts during the conversation (decisions made, milestones reached, problems encountered, preferences expressed, emotional states), call `mempalace_mempalace_kg_add` to record them. Object must be 128 characters or fewer.

**This is mandatory** — record facts you are confident about. Prefer quality over quantity; noisy KG entries degrade retrieval over time.

### Naming reminder
All MemPalace tools use the prefix `mempalace_mempalace_*` (not `mempalace_*`). Examples:
- `mempalace_mempalace_kg_query` (NOT `mempalace_kg_query`)
- `mempalace_mempalace_kg_add`
- `mempalace_mempalace_kg_invalidate`
If you ever catch yourself typing `mempalace_kg_query`, STOP — the correct prefix is `mempalace_mempalace_`.

Complete ~/.config/opencode/opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opencode-mempalace-persistence"],
  "instructions": ["AGENTS.md"],
  "mcp": {
    "mempalace": {
      "type": "local",
      "command": ["mempalace-mcp"],
      "enabled": true
    }
  }
}

Note: identity.txt is NOT listed in instructions — the plugin injects it automatically. It is also NOT in the provider block or permission block — those are optional and depend on your model setup.

5. Alternative: Model-driven memory (without autoInjectContext)

If you prefer the model to search MemPalace on its own via AGENTS.md (requires good model tool-use discipline), set autoInjectContext to false or omit the file:

{
  "autoInjectContext": false
}

AGENTS.md for this mode

Create ~/.config/opencode/AGENTS.md:

# Memory & Knowledge instructions

## CRITICAL: You MUST follow these steps BEFORE every response.

### Step 1 — Search MemPalace
Call `mempalace_mempalace_search` with the user's question or key topics as query. Get the top 5-10 most relevant memory drawers.
**This is mandatory. Never skip this step. No exceptions.**

### Step 2 — Query Knowledge Graph
Call `mempalace_mempalace_kg_query` for entity "user". Then filter the returned facts.

### Step 3 — Record Knowledge Graph facts
After responding, call `mempalace_mempalace_kg_add` for any new facts.

### Naming reminder
All MemPalace tools use the prefix `mempalace_mempalace_*` (not `mempalace_*`).

And keep "~/.mempalace/identity.txt" in instructions in opencode.json since the plugin won't inject it.

Comparison

| Feature | Auto-inject (Recommended) | Model-driven (alternative) | |---------|:-:|:-:| | Memory search | Plugin injects automatically | Model calls mempalace_search | | Identity | Plugin injects automatically | Via instructions: ["identity.txt"] | | AGENTS.md | Minimal (KG only) | Full (search + KG) | | Depends on model discipline | No | Yes |

# Install (requires mempalace>=3.3.5 for HNSW corruption fix)
uv tool install "mempalace>=3.3.5"
# or
pipx install "mempalace>=3.3.5"

# Create palace
mempalace init ~/opencode-memory

# Configure MCP
mempalace mcp

The mempalace mcp command gives you the exact MCP setup string for your configuration.

What happens after installation (auto-inject mode)

You ask a question
  → Plugin hooks into `experimental.chat.messages.transform`
  → Injects your identity + relevant memories from MemPalace
  → Model sees context without having to search

The model responds
  → Plugin detects the response is complete
  → Saves the conversation to MemPalace (flat export, no hardcoded wings)
  → Model records KG facts via MCP tools (mandatory per AGENTS.md)

Next time you ask
  → Plugin finds the previous memory → injects it automatically
  → The cycle continues, memory grows

What gets saved

Every turn (question + answer) is saved as a drawer in MemPalace. No forced categorization — MemPalace's own mining handles organization. The model can optionally record KG facts (decisions, milestones, preferences) during conversation via MCP tools.

Architecture

                 ┌──────────────────────────────┐
                 │         OpenCode              │
                 │                               │
  User msg ─────►│  experimental.chat.messages   │
                 │  .transform hook              │
                 │    ↓                          │
                 │  Injects identity + memories  │
                 │  (autoInjectContext: true)    │
                 │    ↓                          │
                 │  Model sees context → answers │
                 │    ↓                          │
  Answer done ──►│  chat.message + session.idle  │
                 │    ↓                          │
                 │  Query OpenCode DB            │
                 │  since last sync              │
                 │    ↓                          │
                 │  Export → flat text files     │
                 │    ↓                          │
                 │  mempalace mine (async)       │
                 │  single serialized call       │
                 └──────────────────────────────┘
                            │
                            ▼
                 ┌──────────────────────────┐
                 │      MemPalace            │
                 │  ~/opencode-memory/       │
                 │  Vector DB + KG           │
                 └──────────────────────────┘
                            ▲
                            │
                 ┌──────────────────────────┐
                 │  Model (via AGENTS.md)    │
                 │  Records KG facts:       │
                 │  kg_add / kg_invalidate  │
                 └──────────────────────────┘

Relevant files

| File | Purpose | |---|---| | ~/.config/opencode/opencode.json | OpenCode config with plugin + MCP | | ~/.config/opencode/AGENTS.md | Tells the model to manage KG facts | | ~/.mempalace/plugin-config.json | Plugin config (autoInjectContext) | | ~/.mempalace/identity.txt | Your identity (injected by plugin) | | ~/.mempalace/config.json | MemPalace config (palace path) | | ~/.mempalace/knowledge_graph.sqlite3 | Knowledge Graph (structured facts) | | ~/opencode-memory/ | MemPalace vector DB (all drawers) | | ~/.mempalace/sync_state.json | Last sync state |

Install from npm

{
  "plugin": ["opencode-mempalace-persistence"]
}

Local development

{
  "plugin": ["/path/to/opencode-mempalace-persistence/dist/index.js"]
}

Debug logging

export OPENCODE_MEMPALACE_DEBUG=1

When set, the plugin writes a debug log to /tmp/opencode-mempalace.log.

License

MIT