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 mnemosyne add -g or the equivalent global store tool.

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 System

- Use `mnemosyne search -f plain [query]` and `mnemosyne search -g -f plain [query]` to search relevant memories. Use this before making any decisions or taking any actions.
- After significant decisions, use `mnemosyne add "memory content"` to save a concise fact you want to remember. Also do this if the user explicitly asks you to remember something. Use `mnemosyne add -g "memory content"` for cross-project preferences.
- Delete contradicted memories with `mnemosyne delete [memory id]` after storing updated ones with `mnemosyne add ...` or `mnemosyne add -g ...`.
- Mark critical, always-relevant context as core with `-t core`, but use it sparingly. You can also use other tags with repeated `-t` flags, such as `mnemosyne add "database is sqlite" -t core -t tech-stack`.
- 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