@fpytloun/opencode-mnemory

OpenCode plugin for mnemory — persistent AI memory with automatic recall, automatic capture, and 16 explicit memory tools.

No MCP server configuration needed. All memory tools are built into the plugin.

How It Works

Phase	Hook	Action
Session start	session.created	Pre-fetches core memories and instructions from mnemory (non-blocking)
Each user message	chat.message	Starts a semantic search with the user's query (non-blocking)
Before each LLM call	experimental.chat.system.transform	Injects instructions + core memories + search results into system prompt
After each exchange	session.idle	Extracts the last user+assistant exchange and sends to mnemory for memory extraction (fire-and-forget)
On compaction	experimental.session.compacting	Preserves core memories across context window compaction
After compaction	session.compacted	Resets state and re-fetches memories
Session cleanup	session.deleted	Cleans up session state

The LLM also has access to 16 memory tools for explicit operations (search, add, update, delete, artifacts).

Installation

From npm (recommended)

Add to your opencode.json (project) or ~/.config/opencode/opencode.json (global):

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

Set environment variables:

export MNEMORY_URL=http://localhost:8050
export MNEMORY_API_KEY=your-api-key  # if auth is enabled

From local files (for development)

# Global
cp integrations/opencode/*.ts ~/.config/opencode/plugins/

# Or project-level
cp integrations/opencode/*.ts .opencode/plugins/

Configuration

All configuration is via environment variables:

Variable	Default	Description
MNEMORY_URL	http://localhost:8050	Mnemory server URL
MNEMORY_API_KEY	(empty)	Bearer token for authentication
MNEMORY_AGENT_ID	opencode	Agent ID sent to mnemory
MNEMORY_USER_ID	(empty)	User ID (optional if API key maps to user)
MNEMORY_SCORE_THRESHOLD	0.5	Minimum relevance score for recalled memories (0.0-1.0)
MNEMORY_INCLUDE_ASSISTANT	false	Include assistant messages in remember calls
MNEMORY_SEARCH_MODE	search	Default search mode for subsequent turns: find (AI-powered) or search (fast vector)
MNEMORY_FIND_FIRST	true	Use AI-powered search on the first turn of each session
MNEMORY_MANAGED	true	Include mnemory behavioral instructions in the system prompt
MNEMORY_TIMEOUT	30000	HTTP request timeout in milliseconds

Tools

The plugin registers 16 tools that the LLM can call for explicit memory operations:

Tool	Description
memory_search	Semantic search across memories
memory_find	AI-powered multi-query search with LLM reranking
memory_ask	Ask a question and get a synthesized answer from memories
memory_add	Store a new memory (auto-extracts facts, deduplicates)
memory_add_batch	Store multiple memories in one call
memory_update	Update existing memory content or metadata
memory_delete	Delete a memory by ID
memory_delete_batch	Delete multiple memories
memory_list	List memories with optional filters
memory_categories	List available predefined categories
memory_recent	Get recent memories from last N days
memory_save_artifact	Attach artifact (report, code, data) to a memory
memory_get_artifact	Retrieve artifact content
memory_get_artifact_url	Generate signed download URL for large/binary artifacts
memory_list_artifacts	List artifacts attached to a memory
memory_delete_artifact	Delete an artifact

Architecture

index.ts        Plugin entry point — wires hooks + tools
hooks.ts        Lifecycle hooks — auto-recall, auto-remember, compaction
tools.ts        16 custom tool definitions
client.ts       HTTP client for mnemory REST API
helpers.ts      Config, session store, escaping, text extraction

Two-Phase Recall

1. Init recall (session.created): Pre-fetches instructions + core memories (no query). Cached for session lifetime.
2. Per-turn search (chat.message → system.transform): On each user message, starts a search with the user's query. Results are awaited and injected before the LLM call.

First turn uses find mode (AI-powered multi-query search, higher quality). Subsequent turns use search mode (fast vector search, no LLM overhead). Configurable via MNEMORY_SEARCH_MODE and MNEMORY_FIND_FIRST.

Graceful Degradation

• If the mnemory server is offline, the plugin logs a warning and the LLM works normally without memory context.
• All API calls have timeouts and never throw — errors are logged via OpenCode's structured logging.
• Per-turn search has an 8-second timeout in system.transform to avoid blocking the LLM call.

Troubleshooting

Memories not appearing?

• Check that MNEMORY_URL is correct and the server is running
• Look for mnemory: messages in OpenCode logs
• Verify the API key is valid (if auth is enabled)

Search results not relevant?

• Try lowering MNEMORY_SCORE_THRESHOLD (e.g., 0.3)
• Use MNEMORY_FIND_FIRST=true for AI-powered search on the first turn

Too much latency on first turn?

• Set MNEMORY_FIND_FIRST=false to use fast vector search on all turns
• The init recall runs in the background and shouldn't add latency

Development

# Run tests
cd integrations/opencode
bun test

License

Apache 2.0