opencode-memory-plugin

Progressive-disclosure generated memories for OpenCode.

Codex-style generated memory files, but OpenCode-native: compact recall first, source session IDs only when useful, and no repo .opencode/ state.

flowchart TD
  Turn["new OpenCode turn"] --> Summary["tiny memory context"]
  Summary --> Agent["OpenCode agent"]
  Agent --> Remember["remember"]
  Agent --> Need["needs more memory?"]
  Need --> Recall["recall_memory"]
  Recall --> Cards["memory cards"]
  Cards --> Expand["expand_memory"]
  Remember --> Store["OpenCode memory files"]
  Extract["extract_memories"] --> Store
  Store --> Files["memory_summary.md + MEMORY.md"]
  Store --> Summary

What it does

• Writes generated memory files under ${XDG_CONFIG_HOME:-~/.config}/opencode/memories.
• Injects a small memory hint at turn start.
• Nudges the agent to call recall_memory automatically when prior context may matter.
• Keeps memory cards searchable without stuffing full history into context.
• Adds source_thread_ids to extracted facts, decisions, and working context.
• Lets simple explicit preferences stay clean with no session citation.

Memory layers

1. memory_summary.md: tiny always-useful summary.
2. MEMORY.md: searchable generated index.
3. memories.json: canonical store for tools.
4. Sessions: source expansion only when a card needs evidence (via OpenCode read_thread tool).

Tools

• remember: save or update a compact memory.
• recall_memory: search memory cards.
• expand_memory: show full card + source IDs.
• forget_memory: delete a memory.
• list_memories: list cards by type/scope.
• extract_memories: extract durable memories from recent messages (LLM-driven with heuristic fallback).
• memory_files: show generated file paths.
• get_memory_summary: show the compact memory summary.

Source rule: explicit preferences can omit sessions; facts, decisions, and working context default to the current session unless you pass source_thread_ids.

Auto extraction is off by default. When enabled it uses an LLM sub-session (a child of the current session) with no tools and strict JSON output. Heuristic pattern matching is the fallback when the LLM call fails or the fallback is enabled. Enable it with:

export OPENCODE_MEMORY_AUTO_EXTRACT=true

Disable turn-start injection:

export OPENCODE_MEMORY_INJECT=false

Disable the heuristic fallback (fail silent on LLM errors instead):

export OPENCODE_MEMORY_HEURISTIC_FALLBACK=false

Internationalization

The plugin is not fully localized — tool descriptions, error messages, and the generated memory_summary.md header are English. The heuristic path (OPENCODE_MEMORY_HEURISTIC_FALLBACK=true, the default) recognizes English, Chinese, Japanese, and Korean in five places:

| Function | What it does for non-English input | |----------|------------------------------------| | tokenize() | NFKC normalization; unigrams for every CJK/Hangul/Kana char; bigrams only for runs of 3+ chars (avoids single-bigram noise). | | explicitRememberText() | Matches 记住X / 記住：X / 覚えてX / 覚えておいてX / 기억해 X / 기억해둬 X, with the same negative protection as English (不要记住 / 覚えないで / 기억하지 마). | | heuristicExtractMemories sentence splitter | Splits on .!?。！？；…、 and newlines. | | heuristicConfidence() | Chinese/Japanese/Korean high- and low-confidence keywords. | | inferMemoryType() | preference / decision / working-context / fact for Chinese and Japanese. |

The LLM extractor (OPENCODE_MEMORY_AUTO_EXTRACT=true) is told to preserve the user's original language verbatim — it will not translate, transliterate, or romanize. Pass a model with strong multilingual support in extractorModel if your team writes in a language not listed above.

Memory text is stored as written. If you write 记住：使用bun in Chinese, the recall token index will contain 记, 住, 记住, 住使, 使用, bun, so a later query in either language can find it.

Config

Configuration can be provided via environment variables or via plugin options in opencode.json. Options take priority.

| Variable / option | Default | Description | |----------|---------|-------------| | OPENCODE_MEMORY_INJECT / inject | true | Inject memory context at turn start | | OPENCODE_MEMORY_AUTO_EXTRACT / autoExtract | false | Auto-extract memories after each turn | | OPENCODE_MEMORY_HEURISTIC_FALLBACK / extractorFallback | true | Fall back to heuristic when LLM extraction fails | | OPENCODE_MEMORY_EXTRACTOR_MODEL / extractorModel | openai/gpt-5.5 | Model for the LLM extractor sub-session | | OPENCODE_MEMORY_EXTRACTOR_TIMEOUT / extractorTimeoutMs | 90000 | Timeout per extractor sub-session call (ms) | | OPENCODE_MEMORY_HOME / home | ~/.config/opencode/memories | Override memory storage directory |

Plugin options in ~/.config/opencode/opencode.json:

{
  "plugins": [
    {
      "package": "opencode-memory-plugin",
      "options": {
        "autoExtract": true,
        "extractorModel": "anthropic/claude-sonnet-4-5"
      }
    }
  ]
}

Install

Option A: npm package (recommended)

Add to your ~/.config/opencode/opencode.json:

{
  "plugins": ["opencode-memory-plugin"]
}

Option B: symlink for development

mkdir -p ~/.config/opencode/plugin
ln -sf "$(pwd)/src/memory.ts" ~/.config/opencode/plugin/memory.ts

Option C: direct download

mkdir -p ~/.config/opencode/plugin
curl -fsSL https://raw.githubusercontent.com/lleewwiiss/amp-memory-plugin/master/src/memory.ts \
  -o ~/.config/opencode/plugin/memory.ts

Development

bun install
bun run check       # typecheck
bun test            # 109 tests
bun run install:plugin     # copy memory.ts to ~/.config/opencode/plugin/
bun run install:commands   # copy slash commands to ~/.config/opencode/command/

Use OPENCODE_MEMORY_HOME=/tmp/opencode-memory-test for isolated testing.

Slash commands (optional)

The plugin also ships three OpenCode slash commands under src/commands/. They delegate to the same tools the agent can call, but expose them as /memory-summary, /memory-list, and /memory-files in the TUI:

bun run install:commands

MIT. See LICENSE.