https://github.com/kuitos/opencode-claude-memory
🔄 Claude Code-compatible memory for OpenCode — zero config, local-first, no migration.
https://github.com/kuitos/opencode-claude-memory
claude-code memory opencode plugin
Last synced: 2 months ago
JSON representation
🔄 Claude Code-compatible memory for OpenCode — zero config, local-first, no migration.
- Host: GitHub
- URL: https://github.com/kuitos/opencode-claude-memory
- Owner: kuitos
- License: mit
- Created: 2026-03-31T11:59:04.000Z (2 months ago)
- Default Branch: main
- Last Pushed: 2026-04-06T16:58:44.000Z (2 months ago)
- Last Synced: 2026-04-07T02:03:11.088Z (2 months ago)
- Topics: claude-code, memory, opencode, plugin
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/opencode-claude-memory
- Size: 83 KB
- Stars: 9
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
README
# 🧠 Claude Code-compatible memory for OpenCode
**Make OpenCode and Claude Code share the same memory — zero config, local-first, and no migration required.**
Claude Code writes memory → OpenCode reads it. OpenCode writes memory → Claude Code reads it.
[](https://www.npmjs.com/package/opencode-claude-memory)
[](https://www.npmjs.com/package/opencode-claude-memory)
[](https://github.com/kuitos/opencode-claude-memory/blob/main/LICENSE)
[Quick Start](#-quick-start) • [Why this exists](#-why-this-exists) • [What makes this different](#-what-makes-this-different) • [How it works](#-how-it-works) • [Who this is for](#-who-this-is-for) • [FAQ](#-faq)
---
## ✨ At a glance
- **Claude Code-compatible memory**
Uses Claude Code’s existing memory paths, file format, and taxonomy.
- **Zero config**
Install + enable plugin, then keep using `opencode` as usual.
- **Local-first, no migration**
Memory stays as local Markdown files in the same directory Claude Code already uses.
- **Auto-dream consolidation**
Periodically runs a background memory consolidation pass (Claude-style auto-dream gating).
## 🚀 Quick Start
### Prerequisites
- `opencode`
- `python3` available in `PATH`
`python3` 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:
```bash
# 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
```
### 1. Install
```bash
npm install -g opencode-claude-memory
opencode-memory install # one-time: installs shell hook
```
This installs:
- The **plugin** — memory tools + system prompt injection
- The `opencode-memory` **CLI** — wraps opencode with automatic memory extraction + auto-dream consolidation
- A **shell hook** — defines an `opencode()` function in your `.zshrc`/`.bashrc` that delegates to `opencode-memory`
If `python3` is not installed yet, install it first using the commands above before enabling the shell hook.
### 2. Configure
```jsonc
// opencode.json
{
"plugin": ["opencode-claude-memory"]
}
```
### 3. Use
```bash
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:
```bash
opencode-memory uninstall # removes shell hook from .zshrc/.bashrc
npm uninstall -g opencode-claude-memory
```
To print the wrapper package version:
```bash
opencode-memory self -v
```
This removes the shell hook, the CLI, and the plugin. Your saved memories in `~/.claude/projects/` are **not** deleted.
## 💡 Why this exists
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.
## 🧩 What makes this different
Most memory plugins introduce a new storage model or migration step.
This one is a **compatibility layer**, not a new memory system:
- same memory directory conventions as Claude Code
- same Markdown + frontmatter format
- same memory taxonomy (`user`, `feedback`, `project`, `reference`)
- same project/worktree resolution behavior
The outcome: **shared context across Claude Code and OpenCode without maintaining two memory systems.**
## ⚙️ How it works
```mermaid
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`:
1. Shell function intercepts `opencode` command (higher priority than PATH)
2. `opencode-memory` finds the real `opencode` binary in PATH
3. Runs it with all your arguments
4. After you exit, it checks whether the session already wrote memory files
5. If needed, it forks the session with a memory extraction prompt
6. It evaluates the auto-dream gate (default: at least 24h since last consolidation and 5 touched sessions)
7. If the gate passes, it runs a background consolidation pass to merge/prune memories
8. Maintenance runs **in the background** unless `OPENCODE_MEMORY_FOREGROUND=1`
9. Terminal maintenance logs are shown in foreground mode by default, or can be forced on/off with `OPENCODE_MEMORY_TERMINAL_LOG=1|0`
### Runtime dependencies
The wrapper expects `python3` to be available at runtime.
It is used for:
- scoped session selection from `opencode session list`
- parsing `opencode export` output to resolve session directories
- safely identifying and cleaning up forked extraction / auto-dream sessions
Without `python3`, the plugin tools still load, but wrapper maintenance is degraded and fork cleanup is intentionally skipped to avoid deleting the wrong session.
### Compatibility details
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` | `findRelevantMemories.ts` | Memory recall via keyword scoring (heuristic, no LLM side-query) |
| `prompt.ts` | `memoryTypes.ts` + `memdir.ts` | System prompt sections, type taxonomy, truncation |
| `memory.ts` | `memdir.ts` | `truncateEntrypoint()` aligned with `truncateEntrypointContent()` |
## 👥 Who this is for
- You use **both Claude Code and OpenCode**.
- You want **one shared memory context** across both tools.
- You prefer **file-based, local-first memory** you can inspect in Git/worktrees.
- You don’t want migration overhead or lock-in.
## ❓ FAQ
### Is this a new memory system?
No. It is a compatibility layer that lets OpenCode use Claude Code-compatible memory layout and conventions.
### Do I need to migrate existing memory?
No migration required. If you already have Claude Code memory files, OpenCode can work with them directly.
### Where is data stored?
In local files under Claude-style project memory directories (for example, under `~/.claude/projects//memory/`).
### Why file-based memory?
File-based memory is transparent, local-first, easy to inspect/diff/back up, and works naturally with existing developer workflows.
### Can I disable auto extraction?
Yes. Set `OPENCODE_MEMORY_EXTRACT=0`.
### Can I disable auto-dream?
Yes. Set `OPENCODE_MEMORY_AUTODREAM=0`. You can also tune gates with:
- `OPENCODE_MEMORY_AUTODREAM_MIN_HOURS`
- `OPENCODE_MEMORY_AUTODREAM_MIN_SESSIONS`
## 🔧 Configuration
### Environment variables
- `OPENCODE_MEMORY_EXTRACT` (default `1`): set `0` to disable automatic memory extraction
- `OPENCODE_MEMORY_FOREGROUND` (default `0`): set `1` to run maintenance in foreground
- `OPENCODE_MEMORY_TERMINAL_LOG` (default `foreground-only`): set `1` to force terminal logs on, `0` to force them off
- `OPENCODE_MEMORY_MODEL`: override model used for extraction
- `OPENCODE_MEMORY_AGENT`: override agent used for extraction
- `OPENCODE_MEMORY_AUTODREAM` (default `1`): set `0` to disable auto-dream consolidation
- `OPENCODE_MEMORY_AUTODREAM_MIN_HOURS` (default `24`): min hours between consolidation runs
- `OPENCODE_MEMORY_AUTODREAM_MIN_SESSIONS` (default `5`): min touched sessions since last consolidation
- `OPENCODE_MEMORY_AUTODREAM_MODEL`: override model used for auto-dream
- `OPENCODE_MEMORY_AUTODREAM_AGENT`: override agent used for auto-dream
### Logs
Logs are written to `$TMPDIR/opencode-memory-logs/`:
- `extract-*.log`: automatic memory extraction
- `dream-*.log`: auto-dream consolidation
By 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`.
### Concurrency safety
Lock files prevent concurrent extraction/consolidation runs per project root. Stale locks are cleaned up automatically.
## 📝 Memory format
Each memory is a Markdown file with YAML frontmatter:
```markdown
---
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:
- `user`
- `feedback`
- `project`
- `reference`
## 🔧 Tools reference
- `memory_save`: save/update a memory
- `memory_delete`: delete a memory by filename
- `memory_list`: list memory metadata
- `memory_search`: search by keyword
- `memory_read`: read full memory content
## 🧪 Development
```bash
# Run tests
bun test
# Build published artifacts
bun run build
# Release: push to main triggers semantic-release → npm publish
```
## 📄 License
[MIT](LICENSE) © [kuitos](https://github.com/kuitos)