Are you the author? Sign in to claim
OpenCode plugin for Claude Code memory: persistent local Markdown memory shared with Claude Code, zero config, no migrat
Persistent, local-first shared memory for OpenCode and Claude Code — zero config and no migration required.
This OpenCode memory plugin lets OpenCode read and write Claude Code-compatible Markdown memory files, so both CLIs share the same project context.
Claude Code writes memory → OpenCode reads it. OpenCode writes memory → Claude Code reads it.
Quick Start • Why this exists • What makes this different • How it works • Who this is for • FAQ
opencode as usual.opencodepython3 available in PATHpython3 is a runtime dependency for the wrapper's scoped session detection and fork cleanup logic.
If it is missing or not executable, post-session maintenance becomes less reliable: session targeting can fall back to less precise heuristics, and fork cleanup is skipped for safety.
Common install commands:
# macOS (Homebrew)
brew install python
# Ubuntu / Debian
sudo apt-get update && sudo apt-get install -y python3
# Fedora
sudo dnf install -y python3
# Arch Linux
sudo pacman -S python
npm install -g opencode-claude-memory
opencode-memory install # one-time: installs shell hook
This installs:
opencode-memory CLI — wraps opencode with automatic memory extraction + auto-dream consolidationopencode() function in your .zshrc/.bashrc that delegates to opencode-memoryIf python3 is not installed yet, install it first using the commands above before enabling the shell hook.
// opencode.json
{
"plugin": ["opencode-claude-memory"]
}
opencode
That’s it. Memory extraction runs in the background after each session, and auto-dream consolidation is checked with time/session gates.
To uninstall:
opencode-memory uninstall # removes shell hook from .zshrc/.bashrc
npm uninstall -g opencode-claude-memory
To print the wrapper package version:
opencode-memory self -v
This removes the shell hook, the CLI, and the plugin. Your saved memories in ~/.claude/projects/ are not deleted.
If you use both Claude Code and OpenCode on the same repository, memory often ends up in separate silos.
This project solves that by making OpenCode read and write memory in Claude Code’s existing structure, so your context carries over naturally between both tools.
Most memory plugins introduce a new storage model or migration step.
This one is a compatibility layer, not a new memory system:
user, feedback, project, reference)The outcome: shared context across Claude Code and OpenCode without maintaining two memory systems.
graph LR
A[You run opencode] --> B[Shell hook calls opencode-memory]
B --> C[opencode-memory finds real binary]
C --> D[Runs opencode normally]
D --> E[You exit]
E --> F[Extract memories if needed]
F --> G[Evaluate auto-dream gate]
G --> H[Consolidate memories if gate passes]
H --> I[Memories saved to ~/.claude/projects/]
The shell hook defines an opencode() function that delegates to opencode-memory:
opencode command (higher priority than PATH)opencode-memory finds the real opencode binary in PATHOPENCODE_MEMORY_FOREGROUND=1OPENCODE_MEMORY_TERMINAL_LOG=1|0The wrapper expects python3 to be available at runtime.
It is used for:
opencode session listopencode export output to resolve session directoriesWithout python3, the plugin tools still load, but wrapper maintenance is degraded and fork cleanup is intentionally skipped to avoid deleting the wrong session.
The implementation ports core logic from Claude Code for path hashing, git-root/worktree handling, memory format, and memory prompting behavior, so both tools can operate on the same files safely.
Key modules ported from Claude Code's src/memdir/:
| Module | Source | Purpose |
|---|---|---|
memoryScan.ts | memoryScan.ts | Recursive directory scan + frontmatter header parsing |
recall.ts + recallSelector.ts | findRelevantMemories.ts | LLM-selected memory recall + selected memory formatting |
prompt.ts | memoryTypes.ts + memdir.ts | System prompt sections, type taxonomy, truncation |
memory.ts | memdir.ts | truncateEntrypoint() aligned with truncateEntrypointContent() |
No. It is a compatibility layer that lets OpenCode use Claude Code-compatible memory layout and conventions.
No migration required. If you already have Claude Code memory files, OpenCode can work with them directly.
In local files under Claude-style project memory directories (for example, under ~/.claude/projects/<project>/memory/).
File-based memory is transparent, local-first, easy to inspect/diff/back up, and works naturally with existing developer workflows.
Yes. Set OPENCODE_MEMORY_EXTRACT=0.
Yes. Set OPENCODE_MEMORY_AUTODREAM=0. You can also tune gates with:
OPENCODE_MEMORY_AUTODREAM_MIN_HOURSOPENCODE_MEMORY_AUTODREAM_MIN_SESSIONSOPENCODE_MEMORY_EXTRACT (default 1): set 0 to disable automatic memory extractionOPENCODE_MEMORY_FOREGROUND (default 0): set 1 to run maintenance in foregroundOPENCODE_MEMORY_TERMINAL_LOG (default foreground-only): set 1 to force terminal logs on, 0 to force them offOPENCODE_MEMORY_MODEL: override model used for extractionOPENCODE_MEMORY_AGENT: override agent used for extractionOPENCODE_MEMORY_EXTRACT_TIMEOUT_MS (default 120000): positive integer timeout for a native extraction request in millisecondsOPENCODE_MEMORY_EXTRACT_MAX_STEPS (default 30): max agentic steps for a native extraction fork before OpenCode forces a text-only reply; set 0 to remove the cap (the timeout is then the only backstop)OPENCODE_MEMORY_RECALL_MODEL: override model used for LLM memory recall selectionOPENCODE_MEMORY_RECALL_AGENT (default opencode-memory-recall): override agent used for LLM memory recall selectionOPENCODE_MEMORY_AUTODREAM (default 1): set 0 to disable auto-dream consolidationOPENCODE_MEMORY_AUTODREAM_MIN_HOURS (default 24): min hours between consolidation runsOPENCODE_MEMORY_AUTODREAM_MIN_SESSIONS (default 5): min touched sessions since last consolidationOPENCODE_MEMORY_AUTODREAM_MODEL: override model used for auto-dreamOPENCODE_MEMORY_AUTODREAM_AGENT: override agent used for auto-dreamLogs are written to $TMPDIR/opencode-memory-logs/:
extract-*.log: automatic memory extractiondream-*.log: auto-dream consolidationBy default, terminal log lines are only printed when maintenance runs in foreground (OPENCODE_MEMORY_FOREGROUND=1). Background runs stay quiet unless you explicitly set OPENCODE_MEMORY_TERMINAL_LOG=1.
Lock files prevent concurrent extraction/consolidation runs per project root. Stale locks are cleaned up automatically.
Each memory is a Markdown file with YAML frontmatter:
---
name: User prefers terse responses
description: User wants concise answers without trailing summaries
type: feedback
---
Skip post-action summaries. User reads diffs directly.
**Why:** User explicitly requested terse output style.
**How to apply:** Don't summarize changes at the end of responses.
Supported memory types:
userfeedbackprojectreferencememory_save: save/update a memorymemory_delete: delete a memory by filenamememory_list: list memory metadatamemory_search: search by keywordmemory_read: read full memory content# Run tests
bun test
# Build published artifacts
bun run build
# Release: push to main triggers semantic-release → npm publish
Run Claude Code as an MCP server so any agent can delegate coding tasks to it
@microsoft✓ OfficialBrowser automation using accessibility snapshots instead of screenshots
@googleapis✓ OfficialGoogle's universal MCP server supporting PostgreSQL, MySQL, MongoDB, Redis, and 10+ databases
@github✓ OfficialOfficial GitHub integration for repos, issues, PRs, and CI/CD workflows