You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
[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)
16
14
17
15
</div>
18
16
19
17
---
20
18
21
-
## ✨ Features
22
-
23
-
<table>
24
-
<tr>
25
-
<tdwidth="50%">
26
-
27
-
### 🔄 Claude Code Compatible
28
-
Shares the exact same `~/.claude/projects/<project>/memory/` directory — bidirectional sync out of the box
-The**plugin**— memory tools + system prompt injection
78
-
-An`opencode`**wrapper**— auto-extracts memories after each session
37
+
-the**plugin**(memory tools + system prompt injection)
38
+
-an`opencode`**wrapper**(auto-extracts memories after each session)
79
39
80
40
### 2. Configure
81
41
@@ -89,84 +49,89 @@ This installs:
89
49
### 3. Use
90
50
91
51
```bash
92
-
opencode# just use it as usual
52
+
opencode
93
53
```
94
54
95
-
The AI agent can now use memory tools:
55
+
That’s it. Memory extraction runs in the background after each session.
96
56
97
-
-**"Remember that I prefer terse responses"** → saves a `feedback` memory
98
-
-**"What do you remember about me?"** → reads from memory
99
-
-**"Forget the memory about my role"** → deletes a memory
57
+
## 💡 Why this exists
100
58
101
-
When you exit, memories are extracted in the background — zero blocking.
59
+
If you use both Claude Code and OpenCode on the same repository, memory often ends up in separate silos.
102
60
103
-
<details>
104
-
<summary>🗑️ Uninstall</summary>
61
+
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.
105
62
106
-
```bash
107
-
npm uninstall -g opencode-claude-memory
108
-
```
63
+
## 🧩 What makes this different
109
64
110
-
This removes the wrapper and the plugin. Your saved memories in `~/.claude/projects/` are **not** deleted.
65
+
Most memory plugins introduce a new storage model or migration step.
111
66
112
-
</details>
67
+
This one is a **compatibility layer**, not a new memory system:
113
68
114
-
## 💡 How It Works
69
+
- same memory directory conventions as Claude Code
70
+
- same Markdown + frontmatter format
71
+
- same memory taxonomy (`user`, `feedback`, `project`, `reference`)
72
+
- same project/worktree resolution behavior
115
73
116
-
```mermaid
117
-
graph LR
118
-
A[You run opencode] --> B[Wrapper finds real binary]
119
-
B --> C[Runs opencode normally]
120
-
C --> D[You exit]
121
-
D --> E[Get latest session ID]
122
-
E --> F[Fork session + extract memories]
123
-
F --> G[Memories saved to ~/.claude/projects/]
124
-
```
74
+
The outcome: **shared context across Claude Code and OpenCode without maintaining two memory systems.**
75
+
76
+
## ⚙️ How it works
77
+
78
+
1. You run `opencode` (wrapper).
79
+
2. Wrapper finds and launches the real OpenCode binary.
80
+
3. You use OpenCode normally.
81
+
4. After exit, memory extraction runs in the background.
82
+
5. Memories are saved to Claude-compatible paths under `~/.claude/projects/`.
83
+
84
+
### Compatibility details
85
+
86
+
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.
87
+
88
+
## 👥 Who this is for
89
+
90
+
- You use **both Claude Code and OpenCode**.
91
+
- You want **one shared memory context** across both tools.
92
+
- You prefer **file-based, local-first memory** you can inspect in Git/worktrees.
93
+
- You don’t want migration overhead or lock-in.
125
94
126
-
The wrapper is a drop-in replacement that:
95
+
## ❓ FAQ
127
96
128
-
1. Scans `PATH` to find the real `opencode` binary (skipping itself)
129
-
2. Runs it with all your arguments
130
-
3. After you exit, forks the session with a memory extraction prompt
131
-
4. Extraction runs **in the background** — you're never blocked
97
+
### Is this a new memory system?
132
98
133
-
### What "1:1 Replica" Means
99
+
No. It is a compatibility layer that lets OpenCode use Claude Code-compatible memory layout and conventions.
134
100
135
-
Every core component is ported directly from [Claude Code's source](https://github.com/anthropics/claude-code):
No migration required. If you already have Claude Code memory files, OpenCode can work with them directly.
144
104
145
-
This ensures:
146
-
-`~/.claude/projects/<sanitized>/memory/` paths are **byte-identical** to Claude Code's output
147
-
- Git worktrees resolve to the same canonical root
148
-
- Memory files are interchangeable — no migration needed
105
+
### Where is data stored?
149
106
150
-
## ⚙️ Configuration
107
+
In local files under Claude-style project memory directories (for example, under `~/.claude/projects/<project>/memory/`).
151
108
152
-
### Environment Variables
109
+
### Why file-based memory?
153
110
154
-
| Variable | Default | Description |
155
-
|---|---|---|
156
-
|`OPENCODE_MEMORY_EXTRACT`|`1`| Set to `0` to disable auto-extraction |
157
-
|`OPENCODE_MEMORY_FOREGROUND`|`0`| Set to `1` to run extraction in foreground (debugging) |
158
-
|`OPENCODE_MEMORY_MODEL`|*(default)*| Override model for extraction |
159
-
|`OPENCODE_MEMORY_AGENT`|*(default)*| Override agent for extraction |
111
+
File-based memory is transparent, local-first, easy to inspect/diff/back up, and works naturally with existing developer workflows.
112
+
113
+
### Can I disable auto extraction?
114
+
115
+
Yes. Set `OPENCODE_MEMORY_EXTRACT=0`.
116
+
117
+
## 🔧 Configuration
118
+
119
+
### Environment variables
120
+
121
+
-`OPENCODE_MEMORY_EXTRACT` (default `1`): set `0` to disable auto-extraction
122
+
-`OPENCODE_MEMORY_FOREGROUND` (default `0`): set `1` to run extraction in foreground
123
+
-`OPENCODE_MEMORY_MODEL`: override model used for extraction
124
+
-`OPENCODE_MEMORY_AGENT`: override agent used for extraction
160
125
161
126
### Logs
162
127
163
128
Extraction logs are written to `$TMPDIR/opencode-memory-logs/extract-*.log`.
164
129
165
-
### Concurrency Safety
130
+
### Concurrency safety
166
131
167
-
A file lock prevents multiple extractions from running simultaneously on the same project. Stale locks (from crashed processes) are automatically cleaned up.
132
+
A file lock prevents multiple extractions from running simultaneously on the same project. Stale locks are cleaned up automatically.
168
133
169
-
## 📝 Memory Format
134
+
## 📝 Memory format
170
135
171
136
Each memory is a Markdown file with YAML frontmatter:
0 commit comments