opencode-mempalace-persistence 1.2.2 → 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 +122 -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,47 +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)
128
+
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:
110
130
 
111
131
  ```json
112
132
  {
113
- "plugin": ["opencode-mempalace-persistence"],
114
- "mempalace": {
115
- "autoInjectContext": true
116
- }
133
+ "autoInjectContext": false
117
134
  }
118
135
  ```
119
136
 
120
- When enabled, on every user message:
121
- - **First message**: Injects your identity from `~/.mempalace/identity.txt`
122
- - **Every message**: Runs `mempalace search` and injects relevant results
137
+ #### AGENTS.md for this mode
123
138
 
124
- 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`:
125
140
 
126
141
  ```markdown
127
142
  # Memory & Knowledge instructions
128
143
 
129
- ### Step 1 — Query Knowledge Graph
130
- Call `mempalace_mempalace_kg_query` for entity "user" to retrieve relevant facts.
144
+ ## CRITICAL: You MUST follow these steps BEFORE every response.
131
145
 
132
- ### Step 2 — Record Knowledge Graph facts
133
- 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_*`).
134
158
  ```
135
159
 
136
- 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.
137
161
 
138
- **Summary: with vs without autoInjectContext**
162
+ #### Comparison
139
163
 
140
- | Feature | Without (default) | With `autoInjectContext: true` |
164
+ | Feature | **Auto-inject (Recommended)** | Model-driven (alternative) |
141
165
  |---------|:-:|:-:|
142
- | Memory search | Model calls `mempalace_search` (AGENTS.md) | Plugin injects automatically |
143
- | Identity | `instructions: ["identity.txt"]` | Plugin injects automatically |
144
- | AGENTS.md needed | Full (search + KG + identity) | Minimal (KG management only) |
145
- | Depends on model discipline | Yes | No |
146
-
147
- ### 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 |
148
170
 
149
171
  ```bash
150
172
  # Install (requires mempalace>=3.3.5 for HNSW corruption fix)
@@ -163,21 +185,21 @@ The `mempalace mcp` command gives you the exact MCP setup string for your config
163
185
 
164
186
  ---
165
187
 
166
- ## What happens after installation
188
+ ## What happens after installation (auto-inject mode)
167
189
 
168
190
  ```
169
191
  You ask a question
170
- → AGENTS.md tells the model: "search MemPalace first"
171
- → The model calls mempalace_search("question") via MCP
172
- → 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
173
195
 
174
196
  The model responds
175
- → The opencode-mempalace-persistence plugin detects the response is complete
197
+ → Plugin detects the response is complete
176
198
  → Saves the conversation to MemPalace (flat export, no hardcoded wings)
177
- → The model may record KG facts via MCP tools (optional, per-session)
199
+ → Model records KG facts via MCP tools (mandatory per AGENTS.md)
178
200
 
179
201
  Next time you ask
180
- → The model finds the previous memory → coherent responses
202
+ → Plugin finds the previous memory → injects it automatically
181
203
  → The cycle continues, memory grows
182
204
  ```
183
205
 
@@ -192,41 +214,40 @@ Every turn (question + answer) is saved as a drawer in MemPalace. No forced cate
192
214
  ## Architecture
193
215
 
194
216
  ```
195
- ┌──────────────────────────┐
196
- │ OpenCode │
197
- │ │
198
- User msg ─────►│ chat.message hook │
199
- │ ↓ │
200
- │ Query OpenCode DB │
201
- │ (messages since lastSync)│
202
- │ ↓ │
203
- │ Export sessions → flat │
204
- │ (no wing subdirs) │
205
- │ ↓ │
206
- │ Save state immediately │
207
- │ ↓ │
208
- │ mempalace mine (async) │
209
- │ single call, serialized │
210
- │ ↓ │
211
- Session idle ─►│ session.idle hook │
212
- │ (saves last turn) │
213
- └──────────────────────────┘
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
+ └──────────────────────────────┘
214
238
  │
215
239
  ▼
216
240
  ┌──────────────────────────┐
217
241
  │ MemPalace │
218
242
  │ ~/opencode-memory/ │
219
- │ Vector DB │
243
+ │ Vector DB + KG │
220
244
  └──────────────────────────┘
221
245
  ▲
222
246
  │
223
247
  ┌──────────────────────────┐
224
- │ AGENTS.md + MCP │
225
- │ The model searches │
226
- │ MemPalace on every │
227
- │ question. Optionally │
228
- │ records KG facts via │
229
- │ kg_add / kg_invalidate │
248
+ │ Model (via AGENTS.md) │
249
+ │ Records KG facts: │
250
+ │ kg_add / kg_invalidate │
230
251
  └──────────────────────────┘
231
252
  ```
232
253
 
@@ -236,13 +257,14 @@ Every turn (question + answer) is saved as a drawer in MemPalace. No forced cate
236
257
 
237
258
  | File | Purpose |
238
259
  |---|---|
239
- | `~/.config/opencode/opencode.json` | OpenCode config with plugin + MCP + instructions |
240
- | `~/.config/opencode/AGENTS.md` | Tells the model to search MemPalace |
241
- | `~/.mempalace/identity.txt` | Your identity (loaded every session) |
242
- | `~/.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) |
243
265
  | `~/.mempalace/knowledge_graph.sqlite3` | Knowledge Graph (structured facts) |
244
266
  | `~/opencode-memory/` | MemPalace vector DB (all drawers) |
245
- | `~/.mempalace/sync_state.json` | Last sync state (plugin + Python script) |
267
+ | `~/.mempalace/sync_state.json` | Last sync state |
246
268
 
247
269
  ---
248
270
 
@@ -274,21 +296,6 @@ When set, the plugin writes a debug log to `/tmp/opencode-mempalace.log`.
274
296
 
275
297
  ## Recommendations
276
298
 
277
- ### Model choice affects memory retrieval reliability
278
-
279
- 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:
280
-
281
- | Model | Skips search | Mean recall |
282
- |-------|:-:|:-:|
283
- | gemma4:e4b (4B) | **60%** | 0.417 |
284
- | qwen3.5:4b (4B, Tau2-tuned) | **13%** | 0.717 |
285
-
286
- 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.
287
-
288
- ### Forced invocation (belt and suspenders)
289
-
290
- 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.
291
-
292
299
  ### Complementary: upstream OpenCode source adapter
293
300
 
294
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.2",
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",