GitHub - cioffiAI/opencode-memory: Local-first persistent memory plugin for OpenCode: WRITE → DREAM → SURFACE lifecycle, headless consolidation, topic-aware retrieval. · GitHub

/" data-turbo-transient="true" />

Skip to content

Type / to search

Sign in<br>Sign upAppearance settings

You signed in with another tab or window. Reload to refresh your session.<br>You signed out in another tab or window. Reload to refresh your session.<br>You switched accounts on another tab or window. Reload to refresh your session.

Dismiss alert

{{ message }}

cioffiAI

opencode-memory

Public

Notifications<br>You must be signed in to change notification settings

Fork

Star

main

BranchesTags

Go to file

CodeOpen more actions menu

Folders and files<br>NameNameLast commit message<br>Last commit date<br>Latest commit

History<br>6 Commits<br>6 Commits

commands

commands

docs

docs

src

src

tests

tests

.gitignore

.gitignore

CHANGELOG.md

CHANGELOG.md

LICENSE

LICENSE

README.md

README.md

bun.lock

bun.lock

package.json

package.json

tsconfig.json

tsconfig.json

View all files

Repository files navigation

opencode-memory

Demo.mp4

Local-first persistent memory for OpenCode.

opencode-memory gives OpenCode durable memory across sessions through a<br>WRITE → DREAM → SURFACE lifecycle:

WRITE: explicit memory tools

DREAM: headless conversation consolidation

SURFACE: selective memory injection into future prompts

Features

Local JSON storage with file locking

Explicit and inferred memory hierarchy

Cross-language semantic deduplication

Global and project-scoped memories

Selective topic-aware retrieval

Headless child-session consolidation

Orphan child-session garbage collection

No external database

Installation

Add the package to your OpenCode configuration (~/.config/opencode/opencode.json<br>or opencode.jsonc):

"$schema": "https://opencode.ai/config.json",<br>"plugin": [<br>"@cioffi_ai/opencode-memory"

OpenCode installs npm plugins automatically via Bun on startup and caches them<br>in ~/.cache/opencode/node_modules/. Restart OpenCode after adding the entry.

Optional: /memory command

The npm package does not copy commands/memory.md into your user directory<br>(plugin package installs do not run lifecycle scripts). To enable the /memory<br>command, copy it manually from this repository:

mkdir -p ~/.config/opencode/commands

curl -o ~/.config/opencode/commands/memory.md \<br>https://raw.githubusercontent.com/cioffiAI/opencode-memory/main/commands/memory.md

The plugin works without /memory: the memory_read, memory_write,<br>memory_update, memory_forget and memory_clear tools and the automatic<br>DREAM cycle are registered directly by the plugin.

Configuration

Variable<br>Default<br>Effect

OPENCODE_MEMORY_OFF<br>off<br>1 disables the plugin.

OPENCODE_MEMORY_DIR<br>~/.local/share/opencode/memory<br>Data directory (store/state/summary).

OPENCODE_MEMORY_DEBUG<br>off<br>1 enables trace logging.

OPENCODE_MEMORY_DELAY_MS<br>90000<br>Debounce of consolidation after session idle (3s in tests).

OPENCODE_MEMORY_GC_CHILD_AGE_MS<br>600000<br>Min age of an orphan child session before auto-removal.

OPENCODE_MEMORY_INPROGRESS_TIMEOUT_MS<br>600000<br>Expiry of the inProgress marker (crash recovery).

Privacy

Memory files are always stored locally (JSON + lockfile, no external database,<br>no plugin cloud service).

During DREAM consolidation, the conversation is processed by the model provider<br>configured in OpenCode. That provider may be local (e.g. Ollama) or remote (a<br>cloud API): if remote, conversation text is sent to that provider through the<br>same channels OpenCode already uses. For sensitive data, use a local provider<br>or set OPENCODE_MEMORY_OFF=1.

Development

bun install<br>bun run check # typecheck + tests + build<br>npm pack --dry-run

License

MIT — see LICENSE.

About<br>Local-first persistent memory plugin for OpenCode: WRITE → DREAM → SURFACE lifecycle, headless consolidation, topic-aware retrieval.<br>Resources<br>Readme<br>MIT license<br>Activity<br>Stars<br>0 stars<br>Watchers<br>0 watching<br>Forks<br>0 forks<br>Report repository

Releases

Packages

Contributors

Languages

You can’t perform that action at this time.