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