opencode-mnemosyne

Persistent, synced memory for OpenCode using mnemosyne-oss/mnemosyne.

The plugin automatically recalls relevant shared memories for each prompt and injects them as synthetic context. It also provides a mnemosyne tool for explicit search, storage, deletion, and diagnostics.

• Automatic semantic recall on every prompt
• User-wide and project-scoped memory
• Safe failure behavior: OpenCode keeps working when memory is unavailable
• Compaction guidance that preserves memory awareness
• One local MCP subprocess per OpenCode instance
• Compatible with Mnemosyne's encrypted multi-machine sync

Only Mnemosyne's dedicated shared surface is used. Private Hermes memory is not exposed to OpenCode.

• OpenCode
• mnemosyne-memory with MCP support
• A dedicated shared-surface database, optionally synced to your relay

Verify Mnemosyne first:

mnemosyne mcp

If that reports a missing MCP dependency, install the MCP extra in an isolated environment:

uv tool install 'mnemosyne-memory[mcp]'

Add the plugin to ~/.config/opencode/opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["github:evannotfound/opencode-mnemosyne"]
}

The package's prepare script builds dist/ when installed directly from GitHub.

Create ~/.config/opencode/mnemosyne.jsonc:

{
  // Recall relevant memories before every model turn.
  "autoRecall": true,
  "maxMemories": 6,

  // Absolute path is recommended when mnemosyne is installed with uv.
  "memoryCommand": "/Users/you/.local/bin/mnemosyne",

  // This must be the dedicated shared surface, never a private memory DB.
  "sharedDbPath": "/Users/you/.mnemosyne/shared-surface.db",

  // Optional stable ID when the same repository has different folder names.
  "projectId": "evannotfound/my-project"
}

If OPENCODE_CONFIG_DIR is set, place mnemosyne.jsonc directly in that directory instead. The MCP child receives only a small OS launch allowlist and MNEMOSYNE_* variables; unrelated OpenCode and provider credentials are not inherited.

Environment variables override the file:

• MNEMOSYNE_COMMAND
• MNEMOSYNE_SHARED_DB_PATH

The plugin exposes one mnemosyne tool with these modes:

add supports two scopes:

• user: available in every project
• project: tagged with the current project ID and filtered from unrelated projects

Do not store secrets, raw conversations, temporary task progress, logs, or large code excerpts.

Before starting the plugin on a new machine, initialize the dedicated sync surface once:

mkdir -p "$HOME/.mnemosyne"
mnemosyne sync-init --db-path "$HOME/.mnemosyne/shared-surface.db"

Then run Mnemosyne's repeating sync separately from OpenCode on every machine:

mnemosyne sync \
  --db-path "$HOME/.mnemosyne/shared-surface.db" \
  --remote https://memory.example.com \
  --mode bidirectional \
  --interval 30 \
  --api-key-file "$HOME/.config/mnemosyne/sync-api.key" \
  --encrypt-key-file "$HOME/.config/mnemosyne/sync-encryption.key"

Run that as a user service (launchd on macOS or systemd --user on Linux). Keep synchronization out of the plugin so multiple OpenCode processes cannot start competing sync loops.

npm install
npm test
npm run typecheck
npm run build

A real MCP integration test runs when MNEMOSYNE_TEST_COMMAND points to the Mnemosyne executable:

MNEMOSYNE_TEST_COMMAND=/absolute/path/to/mnemosyne npm test

The plugin uses OpenCode's documented chat.message hook for automatic context injection, experimental.chat.system.transform for durable-memory guidance, and experimental.session.compacting to preserve that guidance through compaction. It communicates with Mnemosyne through the official local MCP stdio server rather than reading SQLite directly.

MIT