opencode-mnemosyne

OpenCode plugin for local persistent memory using Mnemosyne. Gives your AI coding agent memory that persists across sessions -- entirely offline, no cloud APIs.

This is the local/offline alternative to cloud-based memory plugins like opencode-supermemory.

Prerequisites

Install the mnemosyne binary first:

# From source (requires Go 1.21+, GCC, Task)
git clone https://github.com/gandazgul/mnemosyne.git
cd mnemosyne
task install

See the mnemosyne README for detailed setup instructions. On first use, mnemosyne will automatically download its ML models (~500 MB one-time).

Install

Add to your opencode.json:

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

That's it. OpenCode will install the plugin automatically.

What it does

Tools

The plugin registers five tools available to the AI agent:

| Tool | Description | |------|-------------| | memory_recall | Search project memory for relevant context and past decisions | | memory_recall_global | Search global memory for cross-project preferences | | memory_store | Store a project-scoped memory (optionally as core) | | memory_store_global | Store a cross-project memory (optionally as core) | | memory_delete | Delete an outdated memory by its document ID |

Hooks

• experimental.session.compacting -- Injects memory tool instructions into the compaction prompt so the agent retains awareness of its memory capabilities across context window resets.

Memory scoping

| Scope | Collection | Persists across | |-------|-----------|-----------------| | Project | <directory-name> | Sessions in the same project | | Global | global | All projects | | Core (project) | <directory-name> (tagged core) | Sessions + survives compaction | | Core (global) | global (tagged core) | All projects + survives compaction |

The project collection is auto-initialized when the plugin loads. The global collection is created on first use of memory_store_global.

AGENTS.md (recommended)

For best results, add this to your project or global AGENTS.md so the agent uses memory proactively from the start of each session:

## Memory (mnemosyne)

- At the start of a session, use memory_recall and memory_recall_global to search for context
  relevant to the user's first message.
- After significant decisions, use memory_store to save a concise summary.
- Delete contradicted memories with memory_delete before storing updated ones.
- Use memory_recall_global / memory_store_global for cross-project preferences.
- Mark critical, always-relevant context as core (core=true) — but use sparingly.
- When you are done with a session, store any memories that you think are relevant
  to the user and the project. This will help you recall important information in
  future sessions.

How it works

Mnemosyne is a local document store with hybrid search:

• Full-text search (SQLite FTS5, BM25 ranking)
• Vector search (sqlite-vec, cosine similarity with snowflake-arctic-embed-m-v1.5)
• Reciprocal Rank Fusion combines both for best results

All ML inference runs locally via ONNX Runtime. Your memories never leave your machine.

Development

This project uses standard Node.js tools: npm for package management and tsc (TypeScript compiler) for building.

# Install dependencies
npm install

# Build the project
npm run build

# Start the compiler in watch mode for development
npm run dev

# Run TypeScript checks
npm run typecheck

License

MIT