opencode-mempalace-persistence 1.2.3 → 1.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +121 -115
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -16,7 +16,7 @@ An OpenCode plugin that automatically saves every conversation to MemPalace and
16
16
  | You repeat context each time | Memory is automatic |
17
17
  | Model starts from scratch each time | Memory persists across sessions |
18
18
 
19
- The model searches MemPalace on every question (via AGENTS.md + MCP), and the plugin saves every response. A perfect feedback loop.
19
+ The plugin injects relevant memories from MemPalace into every prompt (via `experimental.chat.messages.transform`), and saves every response back to MemPalace. A perfect feedback loop.
20
20
 
21
21
  ---
22
22
 
@@ -32,68 +32,86 @@ The model searches MemPalace on every question (via AGENTS.md + MCP), and the pl
32
32
 
33
33
  Add this line to your `~/.config/opencode/opencode.json` and restart OpenCode.
34
34
 
35
- ### 2. Instructions for the model (uses memory)
35
+ ### 2. Identity (who you are)
36
36
 
37
- Create `~/.config/opencode/AGENTS.md`:
37
+ Create `~/.mempalace/identity.txt`:
38
38
 
39
- ```markdown
40
- # Memory & Knowledge instructions
39
+ ```
40
+ I am [name], a [role]. I work with [technologies]. My main projects are [projects].
41
+ ```
41
42
 
42
- ## CRITICAL: You MUST follow these steps BEFORE every response.
43
+ This file is loaded by the plugin — no need to add it to `instructions` in opencode.json.
43
44
 
44
- ### Step 1 — Search MemPalace
45
- Call `mempalace_mempalace_search` with the user's question or key topics as query. Get the top 5-10 most relevant memory drawers.
46
- **This is mandatory. Never skip this step. No exceptions.** Every question — even seemingly trivial ones — may relate to past conversations, projects, or preferences you've forgotten. Searching costs ~nothing; skipping costs continuity.
45
+ ### 3. MemPalace (if not already installed)
47
46
 
48
- ### Step 2 — Query Knowledge Graph
49
- Call `mempalace_mempalace_kg_query` for entity "user". Then filter the returned facts — keep only those whose text contains keywords from the user's question, so irrelevant facts are excluded.
47
+ ```bash
48
+ # Install (requires mempalace>=3.3.5 for HNSW corruption fix)
49
+ uv tool install "mempalace>=3.3.5"
50
+ # or
51
+ pipx install "mempalace>=3.3.5"
50
52
 
51
- ### Step 3 — Use the context
52
- Incorporate relevant memory and facts into your response. If the user's question relates to a past conversation, project, or decision, reference it naturally. If the search returned nothing useful, you are done — do NOT skip steps 1-2 just because you *expect* nothing.
53
+ # Create palace
54
+ mempalace init ~/opencode-memory
53
55
 
54
- ### Naming reminder
55
- All MemPalace tools use the prefix `mempalace_mempalace_*` (not `mempalace_*`). Examples:
56
- - `mempalace_mempalace_search` (NOT `mempalace_search`)
57
- - `mempalace_mempalace_kg_query` (NOT `mempalace_kg_query`)
58
- - `mempalace_mempalace_add_drawer`
59
- - `mempalace_mempalace_get_drawer`
60
- - `mempalace_mempalace_list_wings`
61
- If you ever catch yourself typing `mempalace_search` or `mempalace_kg_query`, STOP — the correct prefix is `mempalace_mempalace_`.
56
+ # Configure MCP
57
+ mempalace mcp
58
+ ```
62
59
 
63
- ## Note
60
+ The `mempalace mcp` command gives you the exact MCP setup string for your configuration.
64
61
 
65
- The KG stores structured facts like: decision (choices made), milestone (completed tasks), problem (issues encountered), preference (likes/dislikes), emotional (feelings). Use these to understand the user's history and context better.
62
+ ### 4. Memory injection (recommended)
66
63
 
67
- ### Knowledge Graph management
64
+ > **Starting from v1.4.0, `autoInjectContext` will default to `true` — this will be the only behavior.**
68
65
 
69
- When you discover structured facts during conversation (decisions made, milestones reached, problems encountered, preferences expressed, emotional states), record them in the Knowledge Graph:
66
+ The plugin automatically injects your identity + relevant memories from MemPalace into every prompt. No model discipline required.
70
67
 
71
- - **New facts**: Call `mempalace_mempalace_kg_add` with subject → predicate → object (e.g. `subject="user"`, `predicate="preference"`, `object="prefers TypeScript over Python"`)
72
- - **Changed facts**: First call `mempalace_mempalace_kg_invalidate` on the old fact, then `mempalace_mempalace_kg_add` for the new one
73
- - **Retrieval**: Call `mempalace_mempalace_kg_query` for entity "user" to see all known facts
68
+ Create `~/.mempalace/plugin-config.json`:
74
69
 
75
- This is optional but recommended — the more facts you record, the better the model understands the user's history and preferences.
70
+ ```json
71
+ {
72
+ "autoInjectContext": true
73
+ }
76
74
  ```
77
75
 
78
- ### 3. Identity (who you are)
76
+ **Do NOT put this in `opencode.json`** — OpenCode's schema validation rejects unknown keys. The plugin reads its config from `~/.mempalace/plugin-config.json` instead.
79
77
 
80
- Create `~/.mempalace/identity.txt`:
78
+ When enabled:
79
+ - **First message**: Injects your identity from `~/.mempalace/identity.txt`
80
+ - **Every message**: Runs `mempalace search` and injects relevant results
81
81
 
82
- ```
83
- I am [name], a [role]. I work with [technologies]. My main projects are [projects].
84
- ```
82
+ #### AGENTS.md for this mode
85
83
 
86
- This is loaded automatically at session start via `instructions` in opencode.json.
84
+ Create `~/.config/opencode/AGENTS.md`:
87
85
 
88
- ### 4. Complete configuration
86
+ ```markdown
87
+ # Memory & Knowledge instructions
89
88
 
90
- `~/.config/opencode/opencode.json`:
89
+ ## CRITICAL: You MUST follow these steps BEFORE every response.
90
+
91
+ ### Step 1 — Query Knowledge Graph
92
+ Call `mempalace_mempalace_kg_query` for entity "user". Then filter the returned facts — keep only those whose text contains keywords from the user's question, so irrelevant facts are excluded.
93
+
94
+ ### Step 2 — Record Knowledge Graph facts
95
+
96
+ After responding, if you discovered any new facts during the conversation (decisions made, milestones reached, problems encountered, preferences expressed, emotional states), call `mempalace_mempalace_kg_add` to record them. Object must be 128 characters or fewer.
97
+
98
+ **This is mandatory** — facts about the user's projects, decisions, and preferences must be saved for future sessions. If you're unsure whether something is a fact, err on the side of saving it. A session with zero KG entries is likely missing important information.
99
+
100
+ ### Naming reminder
101
+ All MemPalace tools use the prefix `mempalace_mempalace_*` (not `mempalace_*`). Examples:
102
+ - `mempalace_mempalace_kg_query` (NOT `mempalace_kg_query`)
103
+ - `mempalace_mempalace_kg_add`
104
+ - `mempalace_mempalace_kg_invalidate`
105
+ If you ever catch yourself typing `mempalace_kg_query`, STOP — the correct prefix is `mempalace_mempalace_`.
106
+ ```
107
+
108
+ #### Complete `~/.config/opencode/opencode.json`
91
109
 
92
110
  ```json
93
111
  {
94
- "model": "opencode/deepseek-v4-flash-free",
95
- "instructions": ["AGENTS.md", "~/.mempalace/identity.txt"],
112
+ "$schema": "https://opencode.ai/config.json",
96
113
  "plugin": ["opencode-mempalace-persistence"],
114
+ "instructions": ["AGENTS.md"],
97
115
  "mcp": {
98
116
  "mempalace": {
99
117
  "type": "local",
@@ -104,48 +122,51 @@ This is loaded automatically at session start via `instructions` in opencode.jso
104
122
  }
105
123
  ```
106
124
 
107
- ### 5. (Optional) Auto-inject memory context
125
+ > Note: `identity.txt` is NOT listed in `instructions` — the plugin injects it automatically. It is also NOT in the `provider` block or `permission` block — those are optional and depend on your model setup.
108
126
 
109
- By default, the model must search MemPalace on its own via AGENTS.md instructions. For models with poor tool-use discipline, enable auto-injection — the plugin injects identity + relevant memories directly into the prompt.
127
+ ### 5. Alternative: Model-driven memory (without autoInjectContext)
110
128
 
111
- Create `~/.mempalace/plugin-config.json`:
129
+ If you prefer the model to search MemPalace on its own via AGENTS.md (requires good model tool-use discipline), set `autoInjectContext` to `false` or omit the file:
112
130
 
113
131
  ```json
114
132
  {
115
- "autoInjectContext": true
133
+ "autoInjectContext": false
116
134
  }
117
135
  ```
118
136
 
119
- **Do NOT put this in `opencode.json`** — OpenCode's schema validation rejects unknown keys. The plugin reads its config from `~/.mempalace/plugin-config.json` instead.
120
-
121
- When enabled, on every user message:
122
- - **First message**: Injects your identity from `~/.mempalace/identity.txt`
123
- - **Every message**: Runs `mempalace search` and injects relevant results
137
+ #### AGENTS.md for this mode
124
138
 
125
- The context is guaranteed regardless of model discipline. Since the plugin handles search and identity injection, you can simplify AGENTS.md — keep only the Knowledge Graph management steps:
139
+ Create `~/.config/opencode/AGENTS.md`:
126
140
 
127
141
  ```markdown
128
142
  # Memory & Knowledge instructions
129
143
 
130
- ### Step 1 — Query Knowledge Graph
131
- Call `mempalace_mempalace_kg_query` for entity "user" to retrieve relevant facts.
144
+ ## CRITICAL: You MUST follow these steps BEFORE every response.
132
145
 
133
- ### Step 2 — Record Knowledge Graph facts
134
- After responding, call `mempalace_mempalace_kg_add` for any new facts found.
146
+ ### Step 1 — Search MemPalace
147
+ Call `mempalace_mempalace_search` with the user's question or key topics as query. Get the top 5-10 most relevant memory drawers.
148
+ **This is mandatory. Never skip this step. No exceptions.**
149
+
150
+ ### Step 2 — Query Knowledge Graph
151
+ Call `mempalace_mempalace_kg_query` for entity "user". Then filter the returned facts.
152
+
153
+ ### Step 3 — Record Knowledge Graph facts
154
+ After responding, call `mempalace_mempalace_kg_add` for any new facts.
155
+
156
+ ### Naming reminder
157
+ All MemPalace tools use the prefix `mempalace_mempalace_*` (not `mempalace_*`).
135
158
  ```
136
159
 
137
- And remove `"~/.mempalace/identity.txt"` from `instructions` in your opencode.json — the plugin injects it automatically.
160
+ And keep `"~/.mempalace/identity.txt"` in `instructions` in opencode.json since the plugin won't inject it.
138
161
 
139
- **Summary: with vs without autoInjectContext**
162
+ #### Comparison
140
163
 
141
- | Feature | Without (default) | With `autoInjectContext: true` |
164
+ | Feature | **Auto-inject (Recommended)** | Model-driven (alternative) |
142
165
  |---------|:-:|:-:|
143
- | Memory search | Model calls `mempalace_search` (AGENTS.md) | Plugin injects automatically |
144
- | Identity | `instructions: ["identity.txt"]` | Plugin injects automatically |
145
- | AGENTS.md needed | Full (search + KG + identity) | Minimal (KG management only) |
146
- | Depends on model discipline | Yes | No |
147
-
148
- ### 6. MemPalace (if not already installed)
166
+ | Memory search | Plugin injects automatically | Model calls `mempalace_search` |
167
+ | Identity | Plugin injects automatically | Via `instructions: ["identity.txt"]` |
168
+ | AGENTS.md | Minimal (KG only) | Full (search + KG) |
169
+ | Depends on model discipline | No | Yes |
149
170
 
150
171
  ```bash
151
172
  # Install (requires mempalace>=3.3.5 for HNSW corruption fix)
@@ -164,21 +185,21 @@ The `mempalace mcp` command gives you the exact MCP setup string for your config
164
185
 
165
186
  ---
166
187
 
167
- ## What happens after installation
188
+ ## What happens after installation (auto-inject mode)
168
189
 
169
190
  ```
170
191
  You ask a question
171
- → AGENTS.md tells the model: "search MemPalace first"
172
- → The model calls mempalace_search("question") via MCP
173
- → Finds relevant memories → gives a better answer
192
+ → Plugin hooks into `experimental.chat.messages.transform`
193
+ → Injects your identity + relevant memories from MemPalace
194
+ → Model sees context without having to search
174
195
 
175
196
  The model responds
176
- → The opencode-mempalace-persistence plugin detects the response is complete
197
+ → Plugin detects the response is complete
177
198
  → Saves the conversation to MemPalace (flat export, no hardcoded wings)
178
- → The model may record KG facts via MCP tools (optional, per-session)
199
+ → Model records KG facts via MCP tools (mandatory per AGENTS.md)
179
200
 
180
201
  Next time you ask
181
- → The model finds the previous memory → coherent responses
202
+ → Plugin finds the previous memory → injects it automatically
182
203
  → The cycle continues, memory grows
183
204
  ```
184
205
 
@@ -193,41 +214,40 @@ Every turn (question + answer) is saved as a drawer in MemPalace. No forced cate
193
214
  ## Architecture
194
215
 
195
216
  ```
196
- ┌──────────────────────────┐
197
- │ OpenCode │
198
- │ │
199
- User msg ─────►│ chat.message hook │
200
- │ ↓ │
201
- │ Query OpenCode DB │
202
- │ (messages since lastSync)│
203
- │ ↓ │
204
- │ Export sessions → flat │
205
- │ (no wing subdirs) │
206
- │ ↓ │
207
- │ Save state immediately │
208
- │ ↓ │
209
- │ mempalace mine (async) │
210
- │ single call, serialized │
211
- │ ↓ │
212
- Session idle ─►│ session.idle hook │
213
- │ (saves last turn) │
214
- └──────────────────────────┘
217
+ ┌──────────────────────────────┐
218
+ │ OpenCode │
219
+ │ │
220
+ User msg ─────►│ experimental.chat.messages │
221
+ │ .transform hook │
222
+ │ ↓ │
223
+ │ Injects identity + memories │
224
+ │ (autoInjectContext: true) │
225
+ │ ↓ │
226
+ │ Model sees context → answers │
227
+ │ ↓ │
228
+ Answer done ──►│ chat.message + session.idle │
229
+ │ ↓ │
230
+ │ Query OpenCode DB │
231
+ │ since last sync │
232
+ │ ↓ │
233
+ │ Export → flat text files │
234
+ │ ↓ │
235
+ │ mempalace mine (async) │
236
+ │ single serialized call │
237
+ └──────────────────────────────┘
215
238
  │
216
239
  ▼
217
240
  ┌──────────────────────────┐
218
241
  │ MemPalace │
219
242
  │ ~/opencode-memory/ │
220
- │ Vector DB │
243
+ │ Vector DB + KG │
221
244
  └──────────────────────────┘
222
245
  ▲
223
246
  │
224
247
  ┌──────────────────────────┐
225
- │ AGENTS.md + MCP │
226
- │ The model searches │
227
- │ MemPalace on every │
228
- │ question. Optionally │
229
- │ records KG facts via │
230
- │ kg_add / kg_invalidate │
248
+ │ Model (via AGENTS.md) │
249
+ │ Records KG facts: │
250
+ │ kg_add / kg_invalidate │
231
251
  └──────────────────────────┘
232
252
  ```
233
253
 
@@ -237,13 +257,14 @@ Every turn (question + answer) is saved as a drawer in MemPalace. No forced cate
237
257
 
238
258
  | File | Purpose |
239
259
  |---|---|
240
- | `~/.config/opencode/opencode.json` | OpenCode config with plugin + MCP + instructions |
241
- | `~/.config/opencode/AGENTS.md` | Tells the model to search MemPalace |
242
- | `~/.mempalace/identity.txt` | Your identity (loaded every session) |
243
- | `~/.mempalace/config.json` | MemPalace config (palace path, wings, keywords) |
260
+ | `~/.config/opencode/opencode.json` | OpenCode config with plugin + MCP |
261
+ | `~/.config/opencode/AGENTS.md` | Tells the model to manage KG facts |
262
+ | `~/.mempalace/plugin-config.json` | Plugin config (`autoInjectContext`) |
263
+ | `~/.mempalace/identity.txt` | Your identity (injected by plugin) |
264
+ | `~/.mempalace/config.json` | MemPalace config (palace path) |
244
265
  | `~/.mempalace/knowledge_graph.sqlite3` | Knowledge Graph (structured facts) |
245
266
  | `~/opencode-memory/` | MemPalace vector DB (all drawers) |
246
- | `~/.mempalace/sync_state.json` | Last sync state (plugin + Python script) |
267
+ | `~/.mempalace/sync_state.json` | Last sync state |
247
268
 
248
269
  ---
249
270
 
@@ -275,21 +296,6 @@ When set, the plugin writes a debug log to `/tmp/opencode-mempalace.log`.
275
296
 
276
297
  ## Recommendations
277
298
 
278
- ### Model choice affects memory retrieval reliability
279
-
280
- Empirical data from the MemPalace community (Cat-9a diagnostic) shows that the model's tool-use discipline significantly impacts how reliably `mempalace_search` is invoked:
281
-
282
- | Model | Skips search | Mean recall |
283
- |-------|:-:|:-:|
284
- | gemma4:e4b (4B) | **60%** | 0.417 |
285
- | qwen3.5:4b (4B, Tau2-tuned) | **13%** | 0.717 |
286
-
287
- For reliable read-side memory retrieval, **Qwen 3.5 4B+ or equivalent** is recommended as the minimum orchestrator. Smaller or older models may skip memory search on most questions regardless of AGENTS.md instructions.
288
-
289
- ### Forced invocation (belt and suspenders)
290
-
291
- A plugin-level config flag that injects a mandatory `mempalace_search` directive into the system prompt (on top of AGENTS.md) can recover ~15pp of recall on low-discipline models. This is being evaluated as a future config option — suggestions welcome.
292
-
293
299
  ### Complementary: upstream OpenCode source adapter
294
300
 
295
301
  The MemPalace project has an upstream PR ([#1484](https://github.com/MemPalace/mempalace/pull/1484)) adding `mempalace mine --source opencode` — a pull-based adapter for retrospective ingest of existing OpenCode sessions. This plugin (push, real-time) and the adapter (pull, backfill) are complementary:
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "opencode-mempalace-persistence",
3
- "version": "1.2.3",
3
+ "version": "1.3.0",
4
4
  "description": "OpenCode plugin — auto-sync conversations to MemPalace memory in real-time. No forced wings, KG extraction via MCP tools.",
5
5
  "main": "dist/index.js",
6
6
  "types": "dist/index.d.ts",