@joe-broadhead/opencode-mem 0.8.5 → 0.9.1

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 (58) hide show
  1. package/CHANGELOG.md +512 -0
  2. package/README.md +127 -61
  3. package/docs/agent-protocol.md +67 -177
  4. package/package.json +1453 -100
  5. package/skills/mem.pages/SKILL.md +146 -0
  6. package/skills/mem.sharing/SKILL.md +91 -0
  7. package/skills/mem.sources/SKILL.md +94 -0
  8. package/skills/mem.usage/SKILL.md +129 -492
  9. package/src/backend/records.js +285 -0
  10. package/src/backend/v3.js +3 -0
  11. package/src/bootstrap.js +49 -45
  12. package/src/call-shapes.js +41 -10
  13. package/src/collector-lock.js +162 -0
  14. package/src/collector-service.js +441 -0
  15. package/src/collector.js +381 -0
  16. package/src/commands.js +3 -3
  17. package/src/config.js +15 -1
  18. package/src/credentials.js +26 -1
  19. package/src/curation.js +1 -1
  20. package/src/permissions.js +87 -10
  21. package/src/protocol.js +29 -20
  22. package/src/recall.js +104 -27
  23. package/src/records-store.js +267 -121
  24. package/src/records.js +63 -11
  25. package/src/runtime.js +23 -14
  26. package/src/skills.js +44 -18
  27. package/src/sources.js +58 -0
  28. package/src/spaces.js +93 -10
  29. package/src/tools/aliases.js +164 -0
  30. package/src/tools/commitments.js +12 -9
  31. package/src/tools/held-write.js +82 -0
  32. package/src/tools/index.js +100 -23
  33. package/src/tools/ingest.js +277 -0
  34. package/src/tools/knowledge.js +6 -1
  35. package/src/tools/memory.js +722 -229
  36. package/src/tools/page.js +423 -0
  37. package/src/tools/recall.js +371 -113
  38. package/src/tools/records-kit.js +142 -0
  39. package/src/tools/share.js +1042 -0
  40. package/src/tools/shared.js +16 -2
  41. package/src/tools/spaces.js +431 -143
  42. package/src/tools/status.js +87 -58
  43. package/src/tools/wiki.js +8 -4
  44. package/src/views/contracts.js +293 -3
  45. package/src/views/inbox-decision.js +59 -0
  46. package/src/views/recall-result.js +12 -0
  47. package/src/views/records-reads.js +675 -0
  48. package/src/views/rpc.js +58 -99
  49. package/src/views/shape.js +61 -0
  50. package/views/commitments.html +4 -0
  51. package/views/graph.html +753 -0
  52. package/views/home.html +11 -5
  53. package/views/journal.html +621 -0
  54. package/views/memory.html +7 -1
  55. package/views/pages.html +636 -0
  56. package/views/recall.html +123 -0
  57. package/views/review.html +406 -0
  58. package/views/today.html +309 -0
package/CHANGELOG.md CHANGED
@@ -3,6 +3,518 @@
3
3
  The format follows Keep a Changelog 1.1.0: one `## [x.y.z] - date` section per
4
4
  release.
5
5
 
6
+ ## [0.9.1] - 2026-11-10
7
+
8
+ Release gate: [evals/results/baseline-2026-11-10-0.9.1-README.md](evals/results/baseline-2026-11-10-0.9.1-README.md): **FAIL on one quality item** (core non-inferiority, `core-wiki-write`), shipped as a recorded decision. Every safety and privacy item passes. The record explains why.
9
+
10
+ 0.9.1 adds the Jelly contracts of issue #33 and fixes what the 0.9.0 audit
11
+ found: erasure, transfer and operator paths that missed the records store, and
12
+ consent wording the plugin could not back. The contracts are
13
+ [docs/design/jelly-contracts-0.9.1.md](docs/design/jelly-contracts-0.9.1.md).
14
+ A 0.8.x or 0.9.0 plugin keeps working against a 0.9.1 server.
15
+
16
+ ### Added
17
+
18
+ - **Jelly contracts (#33).** The `home` and `commitments` views are default
19
+ tiles. `metadata.memoryRecall` carries the recall view's coverage, counts and
20
+ an incomplete flag, never raw hits or withheld text. `memory.overview` reports
21
+ `extraction` (`healthy`, `failing` or `unknown`) from the cell's model shim.
22
+ - **Held team writes** (plugin option `heldTeamWrites: true`): a team
23
+ `mem_remember`, share copy or shared-page write becomes a proposal in the
24
+ author's personal space, and only the author accepts, keeps it private or
25
+ declines it. The Inbox decision route stays off until the host routes it.
26
+ - **Records-aware purge, move and recovery.** Purge removes the space's records
27
+ store and verifies it is gone. A move copies a checksummed online snapshot of
28
+ the records and verifies counts and content before placement changes.
29
+ `space-import.mjs --verify-records-only` checks a restore. Control verifies
30
+ the destination's records before a move or an explicit placement.
31
+
32
+ ### Changed
33
+
34
+ - **Forget is bounded and says so.** It deletes the record, and the atoms that
35
+ state only that fact (paraphrases included). It never deletes a captured turn
36
+ that holds other facts: it shows the turn, which needs the person's separate
37
+ consent. It reports what it searched and what remains, and never says "gone"
38
+ after an incomplete scan. Forgetting an atom reports possible record copies;
39
+ a correction warns about a possibly stale atom.
40
+ - **Consent.** Team-visible writes (`memory.remember`, `memory.revise`,
41
+ `page.write`, `wiki.write`) ask by default. The host's permission policy is the
42
+ person's consent: an answered ask, a configured allow, or a remembered
43
+ "always". The answer says the write was allowed by the permission settings and
44
+ no longer claims the person was asked. A host that cannot add default rules
45
+ refuses team writes unless a rule for that action is configured.
46
+ - **Folder transfer** changes the owner only, pages through large folders and
47
+ reports a partial transfer.
48
+ - **The commitments migration** is made exactly once by a ledger in the records
49
+ service; the hub's `commitments.json` is no longer stamped.
50
+ - **Documentation.** 213 superseded documents carry a "Historical" banner in
51
+ place ([docs/archive-policy.md](docs/archive-policy.md)). Large modules are
52
+ split without a change in behaviour.
53
+
54
+ ### Fixed
55
+
56
+ - A folder transfer cut every page in it to 500 characters (0.9.0).
57
+ - Forgetting a record could delete a whole captured turn with unrelated facts,
58
+ and could report the fact gone after an incomplete scan (0.9.0).
59
+ - Purge left the records store behind; a cross-cell move and the recovery
60
+ procedure skipped it.
61
+ - Restoring or contesting a superseded memory made it current again.
62
+ - A move did not rewrite a page's links to itself; impossible calendar dates and
63
+ inherited kinds were accepted.
64
+ - A page write that meets a newer version says to read the page, merge and
65
+ write again.
66
+ - Flaky tests: stage-ordered deadlines, kernel-assigned ports, readiness and exit
67
+ barriers, and an assertion that matched a random id.
68
+
69
+ ### Upgrade
70
+
71
+ - **Deploy the records service before the plugins:** `records.put` takes
72
+ `migrate_legacy` and keeps the migration ledger.
73
+ - **Held writes** need the same secret `RECORDS_HELD_RECEIPT_KEY` (at least 32
74
+ bytes) on every records cell; without it they fail closed.
75
+ - **Extraction health** needs each cell's private `shim_url` in the gateway's
76
+ cell secrets; without it `extraction` is `unknown`.
77
+ - **Control's records check** reads `CONTROL_RECORDS_CHECKS`,
78
+ `{"<cell id>": {"url": "<records_url>", "key": "<records key>"}}`. A new space
79
+ never waits on it; a move or an explicit placement fails closed without it.
80
+ - **Before a purge or a move,** archive the space, stop and drain its records
81
+ writers and routines, and pass `--confirm-records-quiesced`. Snapshots over
82
+ 95 MiB fail closed. Purge does not erase backups, retained WAL copies,
83
+ temporary snapshots or earlier source copies.
84
+ - **Known limits:** the core extracts from the newest 10 qualified messages of a
85
+ group, and more than 20 turns stamped in one millisecond (a bulk replay) can
86
+ leave a turn unextracted or extract one twice. Jelly's Code Mode does not pass
87
+ inner-call results to the recall view.
88
+
89
+ ## [0.9.0] - 2026-11-09
90
+
91
+ Release gate: [evals/results/baseline-2026-11-09-0.9.0-README.md](evals/results/baseline-2026-11-09-0.9.0-README.md) (PASS).
92
+
93
+ Records become the memory. A new cell service holds memories, pages,
94
+ commitments, review proposals, collected events and the routines' ledger; the
95
+ plugin, the gateway and the views read and write it. The binding contract is
96
+ [docs/design/memory-v1-contracts.md](docs/design/memory-v1-contracts.md).
97
+ A 0.8.4 plugin keeps working against the new gateway. A 0.9 plugin needs the
98
+ records service for memories, pages, sharing and review; `/core` and
99
+ `/knowledge` keep working without it. The 0.9.0 gate is added below. This tree
100
+ does not record a pass.
101
+
102
+ Release gate (contract §7; [gate README](docs/evals/README.md#the-090-gate)):
103
+ core is `2026-11-08.9`, tools is `mem-v090-tools-2026-11-09.3`, and handoff is
104
+ `mem-v090-handoff-2026-11-09.3`. The tools and handoff grader fixes followed
105
+ bugs seen in real runs, with evidence and controls listed in the gate README.
106
+ Core's `core-forget` accepts `mem_revise` forget and checks records as well as
107
+ atoms. The harness sends the §2.2 headers, routes control-mode records calls and
108
+ seeds the injection fixture as pre-existing data. `--instructions none`
109
+ reports the Jelly condition without a protocol file; it is not a gate threshold.
110
+
111
+ ### Added
112
+
113
+ - **`memory-records`, a new cell service** ([records/README.md](records/README.md);
114
+ contract: [docs/design/memory-v1-contracts.md](docs/design/memory-v1-contracts.md) §2).
115
+ Memories, pages, commitments and review proposals as records, the
116
+ collectors' events and their source bindings, and the routines' run ledger,
117
+ in one SQLite file per control space (never per container: legacy personal
118
+ spaces share one). Node 22 built-ins only.
119
+ - The store module `records/src/store.js` (`openStore` → `forSpace`,
120
+ `listSpaces`), shared by the HTTP server, the plugin's test stub and the
121
+ routines: versions and history, `[[links]]` with backlinks and capped
122
+ neighbourhoods, FTS5 search (every word first, then any word), moves that
123
+ rewrite links, section appends, an Obsidian-compatible Markdown export,
124
+ idempotent event ingest with retention, and review that applies, contests
125
+ or turns a rejection into a preference.
126
+ - Access is enforced again in the service: space roles, and page and folder
127
+ grants by the contract's prefix rule; memories and commitments never reach
128
+ a grant. A memory write passes the plugin's curation refusals again (a
129
+ vendored copy, held to the plugin's verdicts by a parity test). The bearer
130
+ is compared in constant time. Missing `RECORDS_API_KEY` fails startup.
131
+ - `POST /v1/<method>` with the gateway's bearer and scope headers, `GET
132
+ /health` (no auth), and the `opencode-mem-records` image
133
+ (`records/Dockerfile`; `node:22-bookworm-slim`, user `node`, volume
134
+ `/data/records`). The routines module is loaded when
135
+ `records/src/routines/` is present. The scheduler stays off until
136
+ `RECORDS_ROUTINES=on` and `RECORDS_LLM_URL` and `RECORDS_LLM_MODEL` are set;
137
+ without those it logs why and does not start.
138
+ - `npm run test:records`; CI also runs the routines' tests on the real
139
+ store and builds the image. A mutation check breaks each access, auth and
140
+ privacy guard and expects the tests to fail.
141
+ - **Gateway `/records`** (contract §3; [deploy/auth/proxy.mjs](deploy/auth/proxy.mjs),
142
+ [deploy/auth/records-guard.mjs](deploy/auth/records-guard.mjs)).
143
+ `POST /records/v1/<method>` is forwarded to the cell's `records_url` with the
144
+ cell's records key and scope headers the gateway builds. No client header is
145
+ copied. A cell with no `records_url`, or whose records health is
146
+ `unhealthy`, answers only `/records` with `503 records_unavailable`. That
147
+ verdict never marks the cell unhealthy for `/core` or `/knowledge`.
148
+ - **Control migrations `016_cells_records_url` and `017_cells_records_health`**
149
+ (SQLite and PostgreSQL). `cells.records_url` is nullable: an existing cell
150
+ keeps working until an operator sets it (`POST /v1/cells`, `PATCH
151
+ /v1/cells/:id`; `null` clears it). The records verdict is stored apart from
152
+ `health_status`. A non-member's grants on a space's `wiki_page` resources
153
+ with a `records:` id are answered by `POST /v1/records/access` (role
154
+ `grant`, prefix rule: `people/ama` never covers `people/amanda`). The owner
155
+ of a records page or folder, or a space admin, can transfer it
156
+ (`POST /v1/spaces/:id/resources/:resource_id/transfer`, audited
157
+ `resource.transfer`); the records service then changes `owner` on the
158
+ records under the path.
159
+ - **Compose, health and backups.** The cell profile in
160
+ [deploy/compose/spaces.yml](deploy/compose/spaces.yml) runs `records` (not
161
+ published, volume `records-data` at `/data/records`). The local seed takes
162
+ the first cell's records URL from `CONTROL_SEED_RECORDS_URL`. `cell-health`
163
+ probes `<records_url>/health` when set and reports it separately.
164
+ [deploy/host/backup-stores.sh](deploy/host/backup-stores.sh) archives the
165
+ records volume as `records.tar.zst` (each `spaces/<space_id>.db` through
166
+ SQLite's online backup). The default volume name is `ocmem-records-data`;
167
+ set `RECORDS_VOLUME` empty to skip a cell that has none. The exporter's
168
+ `spaces_cell_records_unhealthy` alerts as `SpacesCellRecordsUnhealthy`
169
+ (warning, 5 minutes) and does not affect `spaces_cell_up`.
170
+ - **Optional single-host records** (contract §6;
171
+ [deploy/host/run-ocmem.sh](deploy/host/run-ocmem.sh)). The host starts
172
+ records only when the cell opts in. The release script builds its image even
173
+ when it is off; the off-host backup pull includes its archive when present.
174
+ - **Capture agent registry** (contract §2.5 and §5;
175
+ [deploy/auth/proxy.mjs](deploy/auth/proxy.mjs),
176
+ [records/src/store.js](records/src/store.js)). After a successful capture,
177
+ the gateway attempts to register the resolved user and agent with
178
+ `agents.seen` without delaying the response. A later capture retries a
179
+ failed registration. Routines query registered pairs and record authors;
180
+ registry entries unseen for 90 days are removed.
181
+ - **Local stack end-to-end** ([scripts/e2e/README.md](scripts/e2e/README.md)).
182
+ `npm run e2e:stack` runs the plugin against a local compose stack. It is
183
+ separate from `npm test`; its core override disables strict isolation.
184
+ - **Routines, in the records service** (contract §5;
185
+ [records/src/routines/README.md](records/src/routines/README.md)). A
186
+ scheduler every 10 minutes, per space file with new activity: the daily
187
+ journal once the space's local time (the `index` page's `fields.tz`, else
188
+ UTC) is past `RECORDS_ROUTINE_HOUR` (default 18), and again on new activity
189
+ until that journal page is edited; weekly on Monday for the previous week;
190
+ monthly on the 1st. Lint and the dashboard run after each journal. Passes:
191
+ noise filter, thread folding, entity linking, extraction (the model may name
192
+ only ids it was given; quotes required), dedup, the journal page, policy,
193
+ the dashboard. Outputs are `journal/YYYY-MM-DD` (every bullet cited),
194
+ timeline lines on people and project pages, proposals, and the `index` page.
195
+ External text is quoted data; instruction-, permission- and share-shaped
196
+ content from an external author is dropped. Each actual run logs one
197
+ `memory.routine` line (`ok`, `failed` or `budget`; `team` is a hash of the
198
+ space id). A tick that runs nothing does not use that event. The budget is
199
+ `RECORDS_BUDGET_TOKENS` (default 150000) per space per local day.
200
+ - **The plugin's records tools** (contract §4.1). `mem_recall` searches
201
+ records first, then the core's atoms and turns, then documents (`in` narrows
202
+ that). `mem_remember` writes a memory record and answers its `rec_` id at
203
+ once; it no longer writes a turn to the core. `stated_by` is `person` only
204
+ when the person said it, else `agent`. `supersedes` takes `rec_` ids (marked
205
+ superseded) and `m_` ids (the atom is deleted). `mem_revise` corrects,
206
+ confirms, retires, restores, forgets or shows history; forget always asks,
207
+ and also deletes the core's copies of that fact. `mem_page` is authored
208
+ pages (list, read, write, append, move, delete, links, history, export).
209
+ `mem_commitments` is unchanged in its arguments and now stores kind
210
+ `commitment`. `mem_share` grants, revokes, transfers and copies through
211
+ control and records. `mem_spaces` is current, list, members, access, health,
212
+ sources and review. `mem_wiki` stays the documents tool.
213
+ - **The collector** (contract §4.4; [src/sources.js](src/sources.js)). OpenCode
214
+ 2.2.5 gives a plugin no schedule API, so while the engine runs a timer every
215
+ `collectEveryMinutes` (default 30; `collect: false` or `MEMORY_COLLECT=0`
216
+ turns the timer off) collects through the host's tools RPC, as `/mem-collect`
217
+ does. One process per machine holds `collector.lock` beside the spool, with
218
+ a heartbeat; a lease older than 10 minutes is taken over. A missed slot is
219
+ caught up from the cursors. Event ids are idempotent, so a duplicate ingest
220
+ is harmless. The registry is the only place a source is added: `history`,
221
+ `gmail`, `slack`, `x`, `granola`, `plaud`, `wisprflow`, `github`, `linear`,
222
+ each through that plugin's `events_list`. A source is collected only after
223
+ the person binds it. An `events_list` answer without `source` and `account`
224
+ is refused. `mem_ingest` and `mem_cursor` are for the collector; their
225
+ descriptions say agents do not call them. `mem_collect` and `/mem-collect`
226
+ collect on request (`wait: true` waits up to 25 seconds).
227
+ - **Jelly `collect` routine.** `jelly.routines` declares `collect` every 30
228
+ minutes, whose check calls `mem.collect` with an empty input.
229
+ `mem.collect` is declared `allow` and the plugin's own rules leave it
230
+ allowed, so a routine can call it. A Jelly that does not know `routines`
231
+ leaves the field out; the plugin still loads, and the timer still collects
232
+ while the engine is awake.
233
+ - **Five Home views, and seven read-only RPC methods** (14 methods and 8 views
234
+ in all; [docs/jelly.md](docs/jelly.md)). Today, Journal, Review, Pages and
235
+ Graph, next to the 0.8 Home tile, Commitments tile and Your memory section.
236
+ New methods, all `readOnly`: `journal.list`, `journal.read`, `pages.list`,
237
+ `pages.read`, `pages.history`, `graph.links` (permission `mem_page`) and
238
+ `review.list` (permission `mem_spaces`). They read records through the
239
+ plugin's records client, in the person's own scope, with no session.
240
+ `memories.recent` lists records of kind `memory`; the overview counts them.
241
+ A server without records gets one sentence in every view that reads them;
242
+ the Home tile still answers. Review's Accept, Edit and Reject do not call a
243
+ write method: Jelly allows a view only read-only methods, and a view call
244
+ has no session in which to ask. Each starts a message the person sends
245
+ (`open-agent`); the agent decides with `mem_spaces` (`review`, `decide`).
246
+ - **The 0.9.0 gate** (contract §7;
247
+ [docs/evals/README.md](docs/evals/README.md)). Six suites: `change`,
248
+ `paraphrase`, `docs`, `handoff`, `tools`, `injection`, plus answer-only
249
+ views paired with 0.8.4 and a closed book, and a routine-quality runner
250
+ (`scripts/eval/routine-eval.mjs`) over labelled days. `scripts/eval/gate-090.mjs`
251
+ checks pins, zero-tolerance events, safety at 100%, core non-inferior to
252
+ 0.8.4, each suite's primary rule, the answer pairing, the closed book and
253
+ the routine eval. Grader controls: 156 for the six suites
254
+ (`scripts/eval/controls-v1.mjs`) and 11 for the reference routine scorer.
255
+ `paraphrase` and `docs` are at `.2`: a smoke check widened golds that
256
+ rejected a right phrase, before any gate run. No prompt, world, rule or
257
+ `max` changed.
258
+ - **Five blind routine days** ([evals/fixtures/routine-heldout/README.md](evals/fixtures/routine-heldout/README.md)).
259
+ These synthetic days are separate from the days used while fixing routines.
260
+ - **Teaching** (contract §4.6). Four skills, registered natively and declared
261
+ in `jelly.skills`: `mem.usage` (what goes where, recall, remember,
262
+ revise, commitments), `mem.pages`, `mem.sharing`, `mem.sources`. Each
263
+ description is checked to rank first on its own prompts and not to fire on
264
+ unrelated ones (`scripts/skill-triggers.mjs`). Worked calls in the skills are
265
+ checked against the tool schemas. `docs/agent-protocol.md` is generated
266
+ (`npm run gen:protocol`) from the registered tools and the compact block's
267
+ rules, 82 lines; a test fails when it drifts or names a tool or argument
268
+ that is not registered. The file it replaced on this branch was 244 lines
269
+ (0.8.4 shipped 194).
270
+ - **Seven new approval actions** in `jelly.asks` and in the plugin's default
271
+ rules (contract §4.2): `memory.revise` (a team-visible revise, or a proposal
272
+ decided in a shared space), `page.write` (a team-visible page write),
273
+ `page.delete`, `share.grant`, `share.revoke`, `share.transfer` and
274
+ `sources.bind` (every call). The six from 0.8.4 stay. Thirteen in all.
275
+ Private writes do not ask. Deletes, shares and binds do.
276
+
277
+ ### Changed
278
+
279
+ - **Routine extraction** (contract §5;
280
+ [records/src/routines/extract.js](records/src/routines/extract.js),
281
+ [records/src/routines/llm.js](records/src/routines/llm.js)). The model
282
+ request asks for no reasoning by default, with a retry without that field if
283
+ the server rejects it. Extraction anchors a bare ordinal day to the journal
284
+ month when the output repeats it. It rejects decision quotes without choice
285
+ wording and commitment quotes without a recognised work promise. A trigger
286
+ absent from the quote is dropped.
287
+ - **Routine decisions and closures** ([records/src/routines/extract.js](records/src/routines/extract.js)).
288
+ A made choice can be applied; a concrete recommendation becomes a proposal.
289
+ Ideas and deferrals are dropped. A closure needs evidence of completion.
290
+ - **Recall and teaching** (contract §4.1 and §4.6;
291
+ [src/tools/recall.js](src/tools/recall.js),
292
+ [skills/mem.pages/SKILL.md](skills/mem.pages/SKILL.md)). A lexical records
293
+ miss can show bounded, unranked records alongside core hits. The protocol
294
+ teaches a direct read when a named page's body is needed, without a prior
295
+ list, and asks agents to report incomplete searches rather than fan out.
296
+ Recall names the layers searched; a miss is an answer, and a completed answer
297
+ does not need another search. Permission questions recall the recorded rule;
298
+ an unrecorded rule is never presented as recorded. A cited record can support
299
+ an inference under another name when its detail makes the match clear.
300
+ Named page paths can be read directly, and a change needs one append.
301
+ - **Named recall spaces.** `space: "personal"` selects the caller's own space;
302
+ `space: "shared"` selects the bound or only accessible shared space. An
303
+ ambiguous shared selection asks for an id instead of guessing. Neither binds
304
+ the session. `visibility: "private"` is taught for the caller's own memory.
305
+ - **The pinned block** (contract §4.3; [src/bootstrap.js](src/bootstrap.js)) is
306
+ the dashboard page `index` (at most 60 lines), then the Due list, then the
307
+ persona cut to 20 lines. Recall stays pull-based. Instruction-shaped lines
308
+ in the block are withheld, as on recall.
309
+ - **`mem_wiki` is documents only.** Its description points person and project
310
+ pages, and where a project stands, to `mem_page`. A status-shaped
311
+ `mem_remember` now names `mem_page` for the project page's Status section,
312
+ not `mem_wiki`. [docs/local-quickstart.md](docs/local-quickstart.md) teaches
313
+ the 0.9 tools and does not show the deprecated names.
314
+ - **Commitments move once.** The first read or write in a space copies the
315
+ hub's reserved `commitments.json` into commitment records
316
+ ([src/records-store.js](src/records-store.js)). Each keeps its old `cmt_` id
317
+ as `fields.legacy_id`, so that id still addresses it, and
318
+ `fields.migrated_from` is `hub`. The file is then stamped `migrated` and
319
+ kept; a stamped file is not migrated again. A failure is logged and retried
320
+ on the next use, and does not fail the call that triggered it.
321
+ - **The test stub serves the real store** (`records/src/store.js`). The records
322
+ fake is gone. An update sends `base_version` inside the record, which is
323
+ where the store reads it.
324
+ - **Tool descriptions** open with what the tool is for, when to call it, and
325
+ what never to store. Alias descriptions are only `Deprecated: use X`.
326
+
327
+ ### Deprecated
328
+
329
+ Kept for 0.9.x and removed in 0.10. Each description is only the replacement
330
+ ([src/tools/aliases.js](src/tools/aliases.js)):
331
+
332
+ - `mem_forget` → `mem_revise` with `"action": "forget"`. Ids from before 0.9
333
+ (`m_…`, `msg-…`) and `match` keep the old behaviour. A `rec_` id goes to
334
+ `mem_revise`.
335
+ - `mem_promote` → `mem_share` with `"action": "copy"` (and `"revoke"`). A 0.8
336
+ share (`res_…`) is still revoked as before. With no records client, a copy
337
+ falls back to the 0.8 wiki share and says so.
338
+ - `mem_status` → `mem_spaces` with `"action": "health"`.
339
+ - `mem_grants` → `mem_spaces` with `"action": "access"`.
340
+ - `mem_members` → `mem_spaces` with `"action": "members"`.
341
+
342
+ ### Fixed
343
+
344
+ - **The records store refuses to open on a SQLite without FTS5,** with the fix (Node 22.23 or later), instead of failing every write with "no such module: fts5". Node 22.13's `node:sqlite` lacks FTS5; CI now uses Node 22.23.2 (`.nvmrc`). The plugin package never runs SQLite, so its `engines` stay at Node 22.13.
345
+
346
+ - **Personal-space identity** comes from control's caller-specific identity,
347
+ not the order of space memberships ([deploy/auth/control/context.mjs](deploy/auth/control/context.mjs)).
348
+ - **Memory-kind filters retain pre-0.9.0 atoms** in recall
349
+ ([src/tools/recall.js](src/tools/recall.js)).
350
+ - **Routine eval execution** registers the seeded agent and gives each routine
351
+ run its own deadline ([scripts/eval/routine-eval.mjs](scripts/eval/routine-eval.mjs)).
352
+ - **Recall distinguishes an incomplete search from an empty result**
353
+ ([src/recall.js](src/recall.js); contract §4.1). It names a layer or count
354
+ that did not answer, including an unavailable records service, and does not
355
+ claim that nothing is recorded. A page-grant caller does not request
356
+ `space.stats`, which is forbidden for that caller; a miss does not imply an
357
+ empty space or a failed search.
358
+ - **Compose starts auth on a fresh volume**
359
+ ([deploy/compose/spaces.yml](deploy/compose/spaces.yml); contract §6). Auth
360
+ applies missing schema migrations before it listens. The demo seed uses a
361
+ hub-valid wiki id ([control/src/seed.js](control/src/seed.js)); it is a
362
+ catalog fixture, not a created hub wiki.
363
+ - **Routines read core turns under strict isolation** (contract §5;
364
+ [records/src/routines/core.js](records/src/routines/core.js)). Each query
365
+ carries the user and agent in the body and headers, including
366
+ `x-tdai-agent-id`, and uses the space's service id.
367
+ - **An update sent `base_version` beside the record, so every plugin update
368
+ answered `409 version_conflict` on the real store.** The store, the routines
369
+ and the server read it inside the record (`{record: {id, base_version, …}}`).
370
+ The plugin now sends it there. Contract §2.3 and §2.4 say so. The same pass
371
+ aligned the plugin with the answers the service actually gives: error extras
372
+ (`current`, `id`, `binding`, `reason`) inside `error`; history versions'
373
+ `change` and lineage as lists; `records.move`'s `rewritten_links` count and
374
+ `rewritten` ids; ingest's `refused` count and `refusals`; `space.stats`'
375
+ nested counts.
376
+ - **Sharing on a server with no records service** says what is needed, in one
377
+ sentence (`503 records_unavailable`), and changes nothing. Memories stay
378
+ private. This is `mem_share`'s copy, grant, transfer and revoke, and
379
+ `mem_promote`'s copy when a records client exists and the server refuses.
380
+ - **Records health never refuses `/core` or `/knowledge`.** Only `/records`
381
+ answers `503 records_unavailable`. The refusal says memories and recall
382
+ through `/core` still work.
383
+
384
+ ### Security
385
+
386
+ - **The capture registry takes its identity from gateway scope**, not the
387
+ request body (contract §2.5; [records/src/store.js](records/src/store.js)).
388
+ `agents.seen` registers only the caller; the full registry is internal to
389
+ routines. Core reads remain scoped to a user and agent.
390
+ - **Every view page pins its inline scripts by SHA-256** in a meta
391
+ Content-Security-Policy (`default-src 'none'`), including the 0.8 pages.
392
+ Markdown in a view is a safe subset, and every word is set as text, so a
393
+ script in a page or an event title stays text.
394
+ - **The gateway does not copy a client header onto a records request.** Scope
395
+ headers are built from the resolved context. The client's `x-mem-tz` is
396
+ accepted only as an IANA zone, and only to shape dates; it never grants
397
+ access. A caller who is not a member sees only records whose path a grant
398
+ covers, and never a memory or a commitment.
399
+ - **The collector's reserved session allows only the sources' `events_list`.**
400
+ Collection runs in the personal space, and skips before it touches a file
401
+ when there is no credential or no records client.
402
+
403
+ ### Upgrade
404
+
405
+ Server first, then plugins. Routines stay off until you turn them on.
406
+
407
+ **Operators.**
408
+
409
+ 1. Back up the control database and the cell stores before anything else.
410
+ 2. Migrations `016_cells_records_url` and `017_cells_records_health` are pending
411
+ on an existing control database. `CONTROL_MIGRATE=auto` refuses to start
412
+ until they are applied. Apply them once with `CONTROL_MIGRATE=apply` (or
413
+ `npm run migrate -- --apply` in `control/`), then set it back to `auto`.
414
+ Compose auth applies its missing auth schema migrations before it listens,
415
+ including on a fresh volume.
416
+ 3. Deploy control and the gateway. No new gateway secret: the records key is
417
+ an optional `records` field on the cell's existing
418
+ `CONTROL_CELL_SECRETS` entry, and falls back to `core` when it is absent.
419
+ The name `mem-records-key` is the contract's label for that value; the
420
+ scripts read `RECORDS_API_KEY` and the `records` field, not that name.
421
+ 4. Build and run `memory-records`. The image is
422
+ `docker build -f records/Dockerfile -t opencode-mem-records records`. CI
423
+ builds it. The compose cell profile builds and runs it as `records`, not
424
+ published, with volume `records-data` at `/data/records`. Set
425
+ `RECORDS_API_KEY` to the cell's records key; startup fails without it.
426
+ [deploy/host/deploy-release.sh](deploy/host/deploy-release.sh) builds this
427
+ image with auth and control. It records `RECORDS_IMAGE` and starts the
428
+ container only when the cell has opted in (`run/records.env`, or
429
+ `RECORDS_IMAGE` already set). A cell without that opt-in keeps running as
430
+ 0.8 did. The single-host steps are
431
+ [Enable records on a single-host cell](deploy/README.md#enable-records-on-a-single-host-cell).
432
+ There is no `scripts/build-images.sh`.
433
+ 5. Set the cell's `records_url` to the URL the gateway can reach
434
+ (`PATCH /v1/cells/:id`; a plain `http` or `https` URL, no credentials, query
435
+ or fragment). On the compose cell profile the service is `records`, port
436
+ 8430. On a single-host cell the container is `ocmem-records`, port 8430. A local seed
437
+ reads `CONTROL_SEED_RECORDS_URL`. Until it is set, `/records`
438
+ answers `503 records_unavailable` and `/core` and `/knowledge` are
439
+ unchanged.
440
+ 6. Backups: [deploy/host/backup-stores.sh](deploy/host/backup-stores.sh)
441
+ expects the records volume. Its default name is `ocmem-records-data`; the
442
+ compose volume is `records-data` (plus the project prefix), so set
443
+ `RECORDS_VOLUME` to the volume that holds `/data/records`. The archive is
444
+ `records.tar.zst`. The restore drill requires it unless `RECORDS_VOLUME` is
445
+ empty.
446
+ 7. Leave routines off for the cutover (`RECORDS_ROUTINES` defaults to `off`).
447
+ Turn them on later, in the records container: `RECORDS_ROUTINES=on`,
448
+ `RECORDS_LLM_URL` (in a cell, the shim's own URL plus `/v1`),
449
+ `RECORDS_LLM_MODEL`, and `RECORDS_CORE_URL` plus `RECORDS_CORE_KEY` so a
450
+ journal can read the day's turns. Missing LLM settings leave the scheduler
451
+ off and log the reason. A failing records service still does not take
452
+ `/core` down. For strict isolation, routines use the space's service id
453
+ and query each user and agent separately. `RECORDS_CORE_SERVICE_ID` is the
454
+ fallback when the space has no service id
455
+ ([routines configuration](records/src/routines/README.md#configuration)).
456
+ The gateway's capture registry lets routines find capture-only agents.
457
+ Journals cover capture-only agents registered since 0.9.0; the registry is
458
+ not backfilled and removes entries unseen for 90 days.
459
+
460
+ **People and agents.**
461
+
462
+ - The tools to use are `mem_recall`, `mem_remember`, `mem_revise`, `mem_page`,
463
+ `mem_commitments`, `mem_share` and `mem_spaces`. `mem_wiki` is documents
464
+ (uploads and the pages synthesised from them). `mem_ingest` and `mem_cursor`
465
+ belong to the collector.
466
+ - The old names still work for this release, each described only as
467
+ `Deprecated: use X`: `mem_forget` → `mem_revise` forget; `mem_promote` →
468
+ `mem_share` copy (and revoke); `mem_status` → `mem_spaces` health;
469
+ `mem_grants` → `mem_spaces` access; `mem_members` → `mem_spaces` members.
470
+ They go in 0.10.
471
+ - `mem_remember` answers a `rec_` id at once. It does not write a turn to the
472
+ core. Recall still reads core atoms and turns after records, so a server
473
+ without records still recalls what 0.8 stored. Remember, pages, sharing and
474
+ review need the records service; without it they say so and change nothing.
475
+ - The first use of commitments in a space migrates the hub file once, keeps
476
+ it, and still accepts the old `cmt_` ids.
477
+ - Collection does not start by itself for a source. The person binds an
478
+ account with `mem_spaces` (`sources`, `bind`); that asks `sources.bind` and
479
+ shows the signed-in account. What is collected, after that, is `events_list`
480
+ from the nine registered sources (history, Gmail, Slack, X, Granola, Plaud,
481
+ Wispr Flow, GitHub, Linear), while OpenCode is running, every 30 minutes,
482
+ one process per machine. A source plugin whose `events_list` does not answer
483
+ `source` and `account` is refused; those plugins publish that contract on
484
+ their own, and this release does not assume they have. Turn the timer off
485
+ with `collect: false` or `MEMORY_COLLECT=0`; `mem_collect` and
486
+ `/mem-collect` still run on request. Turn a source off with `unbind` and
487
+ `confirm: true`: collection stops and that source's events are deleted.
488
+ Journal pages and memories already made from them stay.
489
+ - OpenCode operators who want the full protocol still name
490
+ `docs/agent-protocol.md` in `instructions`
491
+ ([docs/agent-setup.md](docs/agent-setup.md)). That file is now generated.
492
+
493
+ **Jelly.**
494
+
495
+ - `mem.collect` is allowed, and never asks. The `collect` routine is declared
496
+ every 30 minutes and calls it. Accept it with the rest of the card (below)
497
+ if this agent should be woken to collect; the in-plugin timer still collects
498
+ while the engine is awake either way.
499
+ - Seven new asks: `memory.revise`, `page.write`, `page.delete`, `share.grant`,
500
+ `share.revoke`, `share.transfer`, `sources.bind`. They are in `jelly.asks`.
501
+ A tightening applies at once. Private writes still do not ask.
502
+ - Eight views and 14 read-only methods. The five new Home widgets are Today,
503
+ Journal, Review, Pages and Graph. Review decisions are a message the person
504
+ sends, not a view write.
505
+ - An agent already on 0.8.4 needs one Accept on the plugin's card before the
506
+ new tools, views, skills and the collect routine run. Those are a loosening,
507
+ so they wait under Changes to review. The 0.8.3 optional-input change put
508
+ nothing there; this one does
509
+ ([docs/jelly.md](docs/jelly.md) Versions).
510
+ - Jelly's agents get the always-on short block plus the four skills, not
511
+ `docs/agent-protocol.md`. The short block is the eight rules in
512
+ [src/protocol.js](src/protocol.js), injected as `<mem_protocol>` when the
513
+ prompt does not already teach memory. The document's tool map and the rest
514
+ are not in that prompt, so the short block has to stand on its own. The
515
+ skills (`mem.usage`, `mem.pages`, `mem.sharing`, `mem.sources`) load when
516
+ their descriptions match.
517
+
6
518
  ## [0.8.5] - 2026-11-08
7
519
 
8
520
  One fix, for Jelly's hosted agents ([#31](https://github.com/joe-broadhead/opencode-mem/issues/31)).