Persistent cross-session memory for OpenCode.
A durable knowledge base rooted at ~/opencode-memory/ — a git-tracked tree of markdown notes — paired with a hybrid keyword + semantic search layer. The OpenCode plugin provides tools, hooks, auto-applied config, and a bundled skill.
LLM agents forget everything between sessions. That means rediscovering the same repo structure, tool quirks, and gotchas over and over. This plugin gives them a place to put that knowledge and a strong enough social contract (tool-call tracking, compaction-time retrospectives) that they actually use it.
| Category | Additions |
|---|---|
| Memory tools | memory_search, memory_list, memory_save, memory_access, memory_setup |
| Session tools | session_search, session_read, session_list (OpenCode only — read OpenCode's SQLite history) |
| Hooks | Search-first nudge at 8 tool calls; discovery nudge on subagent outputs; retrospective reminder at compaction time (OpenCode only) |
| Skill | opencode-memory — auto-registered in OpenCode, dropped at ~/.agents/skills/opencode-memory for Zed & Pi |
| Agent prompts | Built-in subagents (general, explore, research, review, investigator) get a memory-aware prompt prepended non-destructively (OpenCode only) |
Then bootstrap the memory directory + embedding model + skill:
bunx @mathew-cf/opencode-memory initThis creates ~/opencode-memory/ (git repo, 7 category subdirs), downloads the ~90MB embedding model, and symlinks the bundled skill into ~/.agents/skills/opencode-memory (where Zed and Pi look). Idempotent — safe to re-run. Pass --skip-model to defer the download, --skip-skills to skip the symlink.
The plugin also auto-registers (OpenCode only):
- its bundled skill under
config.skills.paths - edit + external-directory permissions for
~/opencode-memory/** - memory-aware prompt prefixes on the five built-in subagents (only when their prompt isn't already set)
memory_search combines two complementary signals:
| Backend | Package | Purpose |
|---|---|---|
| Keyword (ripgrep) | @vscode/ripgrep |
Exact-match + phrase lookup over files |
| Semantic (rag-cli) | @mathew-cf/rag-cli |
Similarity search via local embeddings |
Both are declared as required dependencies: installing the plugin pulls in prebuilt binaries for your platform automatically (macOS ARM64/x64, Linux x64/ARM64; ripgrep additionally covers Windows and FreeBSD). No Rust toolchain, no brew install, no $PATH plumbing.
Pre-cache the embedding model once (~90MB) to make the first semantic search instant:
rag downloadIf either dependency fails to install (unusual — usually indicates an unsupported platform), the plugin transparently degrades. memory_setup reports which backends are resolvable and prints targeted install guidance for each.
bunx @mathew-cf/opencode-memory initCreates ~/opencode-memory/ (or $OPENCODE_MEMORY_DIR), runs git init, scaffolds the 7 advisory category subdirs (preferences/, repos/, technical/, people/, workflows/, snippets/, notes/), and pre-caches the embedding model for semantic search.
Subcommands:
| Command | Purpose |
|---|---|
bunx @mathew-cf/opencode-memory init |
Create + git-init memory dir, download embedding model |
bunx @mathew-cf/opencode-memory init --skip-model |
Same, but skip the ~90MB download |
bunx @mathew-cf/opencode-memory status |
Report which search backends are resolvable |
Memory files are plain markdown with a small frontmatter block:
---
title: Framework uses custom error hierarchy
tags: [framework, error-handling]
summary: All errors must extend AppError; plain Error bypasses formatting
created: 2025-01-15
updated: 2025-01-15
importance: high
source: Code inspection of src/errors/
source_date: 2025-01-15
---
All errors in `src/errors/` must extend `AppError`. Throwing plain `Error`
bypasses the error formatter → raw 500s. Gotcha: `AuthError` must include a
`realm` field or auth middleware silently ignores it.After writing or editing files, call memory_save — it runs git add -A + commit and kicks off a background rag index re-build.
memory_search("retry jitter") # hybrid rg + rag
memory_search("auth", category="repos") # filter to a category
memory_list() # browse categories + counts
memory_list("technical") # list files in one category
See the bundled skill (skills/opencode-memory/SKILL.md) for the full protocol.
The plugin installs two hooks:
Tracks tool usage per session and injects short reminders into tool output when:
- 8 tool calls deep with no search: reminds the agent to call
memory_searchandsession_searchbefore going further. - A subagent's output contains "Discoveries worth saving": reminds the parent to actually save them, not defer to session end.
Reminders fire at most once per session each to avoid spam.
Injects memory-specific preservation rules so references to saved files and search results survive summarization. If the session is >10 tool calls and never called memory_save, adds a retrospective reminder.
bun install
bun run typecheck # tsc --noEmit
bun test # 118 tests across 7 files
bun run build # bundle to dist/Apache-2.0 — see LICENSE.