OpenCode Short-Term Memory

Automatically updates structured memory for each conversation and brings useful saved context back into later requests. OpenCode V1 and V2 support the same core features through their native server and terminal UI integrations.

Unofficial plugin; not affiliated with or maintained by the OpenCode team.

What it does

• Summarizes visible conversation into User Instructions, Long Horizon Context, Decisions, Conclusions and Active References.
• Updates in the background after idle and attempts a refresh before compaction.
• Uses a separate clean summarizer session by default, or the active conversation when configured. An explicit memory model works in either mode.
• Delivers saved memory as a session message without requesting a reply by default. Optional system/context transformation is available in clean mode.
• Gives task sub-agents a frozen snapshot of their parent's saved memory.
• Provides a native /stm menu with scrolling results and agent-facing tools.
• Saves readable Markdown locally. Reset clears saved memory and starts future updates after a persistent history boundary without deleting the conversation.

Memory is an LLM summary, not a complete transcript or guaranteed instruction store. Provider credentials, model compatibility and quotas are managed by OpenCode; STM generation consumes that model's usage allowance.

Install

These guides describe 1.4. The examples pin 1.4.0 for reproducible installation; use @latest to select npm's current stable release. See the changelog for release history.

OpenCode V1: run from your project for a local installation:

opencode plugin '@atonev/opencode-short-term-memory@1.4.0' --force
# Or install globally:
opencode plugin '@atonev/opencode-short-term-memory@1.4.0' --global --force

Enable the same package in the singular plugin arrays of server opencode.json and terminal UI tui.json.

OpenCode V2: the installation command is global:

opencode plugin add '@atonev/opencode-short-term-memory@1.4.0'

Enable the same package in the plural plugins arrays of global server opencode.json and terminal UI cli.json. Keep server and UI versions aligned; server tools alone do not establish that the terminal menu is loaded.

See installation and configuration for config examples, paths, automatic setup and supported installation routes.

Use it

Open a conversation and select /stm from native autocomplete to open the picker. Use the bare menu; /stm show and /stm-cmd are not current command formats.

Action	Result
Show memory	Current session's saved Markdown.
Logs	Absolute log-file path on the OpenCode server.
Settings	Effective options and configuration paths.
Status	Memory path/size, model and live diagnostic counters.
Update	Requests an eligible memory update; uses the memory model.
Reset	Confirms before clearing saved memory and setting a history boundary.
Create example config	Optional customization; preserves existing STM config.

Menu actions run without asking the chat model to select a tool or explain the result. Update alone can call the memory model. Use Up/Down, PgUp/PgDn and Home/End to navigate results, and Esc to close. Logs returns a path only: inspect that file yourself on the server.

Both versions also expose seven dedicated stm_memory_* tools and the short_term_memory compatibility wrapper. Asking the chat agent to use them can involve the main model. See commands and tools.

Configure

Supported native installations create a minimal stm.json on first activation, without replacing existing stm.json or stm.jsonc. Optional example creation is not a prerequisite. If the installation origin cannot be verified, Settings explains why automatic creation was skipped.

All settings are optional. For a separate memory model and reminders every four eligible user turns:

{
  "summarizerMode": "clean",
  "memoryModel": "your-provider/your-model",
  "remindEveryN": 4,
  "enableLegacyPeriodicSystemTransform": false,
}

Leave memoryModel blank to use OpenCode's fresh-session default in clean mode, or the session model in active mode. Configure authentication and provider options in OpenCode first.

Set enableLegacyPeriodicSystemTransform: true for primary system/context reminders in clean mode. Active mode always uses session-message delivery. Message delivery avoids rewriting the system prefix; actual provider cache reuse and billing remain provider-dependent. In V2, the transcript may show only a Short-term session memory label; Show reads the saved text.

See the full settings reference, generation guide and delivery guide.

Local files and limits

Memory defaults to .opencode/memory, relative to the server's working directory. Use Status to find the actual file. Keep memory private and ignore it in Git where appropriate: stored summaries are plain text and can contain conversation details.

Reset does not erase chat history, previous injection messages or existing child snapshots. New conversation can reintroduce old facts. Updates checkpoint successful chunks; a later failure can leave earlier progress saved.

Diagnostic logs omit prompt/memory dumps and redact recognized credentials. Redaction is best effort; memory, model inputs and older logs are not scrubbed. Inspect files before sharing them.

Memory files and reset explains storage and cleanup. Child sessions and compression covers snapshot timing and the completed-compress bridge. The feature comparison and V1/V2 differences describe host-specific limits.

See the documentation index for all guides. Release history, fixes and acceptance records are separate from these current-feature guides.