@joe-broadhead/opencode-mem 0.9.2 → 0.9.5

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.
package/CHANGELOG.md CHANGED
@@ -3,6 +3,330 @@
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.5] - 2026-11-11
7
+
8
+ Release gate: PASS ([evals/results/gate-2026-11-11-0.9.5-README.md](evals/results/gate-2026-11-11-0.9.5-README.md)).
9
+
10
+ **0.9.5 ships 0.9.4's changes** (below; 0.9.4 itself was not released: its gate was VOID, with `core-forget` failing one of three attempts, a safety item; see [evals/results/gate-2026-11-10-0.9.4b-README.md](evals/results/gate-2026-11-10-0.9.4b-README.md)), together with the fix for that failure (forget fingerprints: recall withholds copies of forgotten text, [docs/design/adr-forget-copies.md](docs/design/adr-forget-copies.md)), the redesigned console, `/connect` sign-in, capture path redaction and the Jelly view fixes (#51–#53).
11
+
12
+ **Deploy order:** the records service first (it adds `forgotten.*`), then the gateway, then the plugin. A plugin before 0.9.5 never withholds forgotten text.
13
+
14
+ ### Added
15
+
16
+ - **A themeable console, and Sharing in it**
17
+ ([docs/design/console-redesign.md](docs/design/console-redesign.md)). The
18
+ gateway serves area pages at `/console/<area>` on semantic theme tokens; a
19
+ deployment brands them with `CONSOLE_THEME_DIR` (`theme.css`, `logo.svg`,
20
+ `fonts/`), and the neutral default ships here. `/console/sharing` lists,
21
+ grants, revokes, transfers and copies, as the signed-in person, through the
22
+ same `/v1` and records handlers the plugin reaches. Every change is
23
+ previewed in a dialog before it is made. `/login` and `/account` use the
24
+ theme. `scripts/check-console-theme.mjs` checks a theme's tokens and AA
25
+ contrast; `scripts/console-shots.mjs` screenshots the pages per theme.
26
+ - **Forgotten, in the console** (Memories). A forget in the console now leaves
27
+ the same fingerprint the plugin's does (`forgotten.put`), so the plugin's
28
+ recall withholds the copies. A **Forgotten** list shows the person's own
29
+ entries by date, kind and space (never text), and **Lift** shows a forgotten
30
+ text's copies in recall again, with a preview. Lifting is the person's alone:
31
+ it runs only in the browser session (an API key, a connect token and a header
32
+ a client makes up all get 403). The console cannot delete the kept turns, and
33
+ says "Ask your agent to delete them; recall won't show them meanwhile."
34
+ - **Account in the console** (`/console/account`,
35
+ [docs/design/console-redesign.md](docs/design/console-redesign.md), slice S9).
36
+ API keys: list, create (the key is shown once, with a copy button and the
37
+ plugin config), rename, revoke. Connected sign-ins: list (the device's label
38
+ shown as unverified text), revoke one, sign out everywhere. Each change is
39
+ previewed first. A short how-to for `/connect`. `/account` stays as the plain
40
+ page.
41
+ - **Account management needs a browser session.** The Account routes refuse an
42
+ API key and a `/connect` sign-in with `403 session_required`, reads included,
43
+ before any other check; bearer tokens keep using the console's other areas,
44
+ as the plugin can. The rule and every route are in
45
+ [docs/design/console-write-paths.md](docs/design/console-write-paths.md).
46
+ - **Console write paths, written down**
47
+ ([docs/design/console-write-paths.md](docs/design/console-write-paths.md)).
48
+ Every console write route with its checks (JSON, Origin, CSRF token), the
49
+ in-process handler it calls, who may do it and the test that covers it, for
50
+ an independent review. `test/console-integration.test.js` opens every area
51
+ of the integrated console, checks none says "soon", and checks the document
52
+ lists every area write route.
53
+ - **Commitments, Review and Sources in the console**
54
+ ([docs/design/console-redesign.md](docs/design/console-redesign.md), slices
55
+ S3, S6, S7). `/console/commitments` lists (overdue first), adds, completes,
56
+ snoozes (a new due date), edits and deletes the person's private
57
+ commitments; an instruction in one is refused with the plugin's own
58
+ patterns. `/console/review` shows the routine's proposals and the team
59
+ writes held for the person, and each decision (accept, keep private,
60
+ decline) opens on exactly what would be written, and where; a held write
61
+ reaches the shared space only when accepted. `/console/sources` lists the
62
+ accounts Memory collects from, confirms the account a source reported before
63
+ collecting, and previews the events an unbind deletes. All are previewed,
64
+ CSRF-protected, and run through the same records handler the plugin uses.
65
+
66
+ - **Memories and Profile in the console.** `/console/memories` searches and
67
+ browses the person's memories by type and status, adds, corrects, confirms,
68
+ retires, restores and forgets them, with each memory's history. A forget
69
+ previews what is deleted (the memory and its history), what stays (records
70
+ that superseded it, and the core's atoms and turns found by a bounded
71
+ search, with whole turns held for separate consent), and states that the
72
+ coverage is incomplete; after it, the result is read back. The console never
73
+ deletes a core atom or turn. `/console/profile` shows the persona and
74
+ scenarios Memory holds, labelled as data, and erases a phrase from them: the
75
+ preview lists the exact lines, the result is read back and says where the
76
+ phrase remains. Both act as the person, through the records handlers and the
77
+ core reads Mission Control already makes; no new privilege.
78
+
79
+ - **Pages and Wiki in the console.** `/console/pages` lists pages by folder
80
+ and type, reads them as safely rendered Markdown with `[[links]]` that
81
+ open in place, and writes, appends to a section, moves, deletes, and shows
82
+ history and links, through the records handler as the signed-in person.
83
+ Every change is previewed first; a page changed since it was read is a
84
+ conflict the person merges, never an overwrite; a viewer cannot write and
85
+ only an admin or owner can delete, as for the plugin. `/console/wiki` lists,
86
+ searches and reads a space's wikis through the data plane's own handler
87
+ (`acting.core`), so the control catalog decides which wikis are visible.
88
+ Page text is only ever text: no script or markup is made from it.
89
+
90
+ - **Spaces in the console** (`/console/spaces`): the spaces a person can use,
91
+ who is in each, their own access (role, and the grants that name them), and
92
+ each space's health (what it holds, the memory service, the personal cell's
93
+ extraction verdict). Read-only, as `mem_spaces`: membership and roles stay
94
+ the control plane's. Each section loads on its own, so one failing read
95
+ never blanks the others.
96
+ - **Sharing: pick, don't type.** "Take back copies" lists the person's own
97
+ copies in the space to tick, and "Share with" suggests the space's members
98
+ and the groups and roles its shares already name (typing an email still
99
+ works). The control plane has no directory of groups and roles a person may
100
+ read, so only those already in use here are suggested.
101
+
102
+ - **Sign in with `/connect`** (lane AUTH-CONNECT,
103
+ [docs/design/plugin-sign-in.md](docs/design/plugin-sign-in.md)). In
104
+ OpenCode 2.2 or newer, `/connect` → **Memory** opens the browser; the person
105
+ signs in with Google and approves the code OpenCode shows. OpenCode stores
106
+ the credential and renews it: a 30-minute access token and a single-use
107
+ refresh token; a refresh token used twice ends the sign-in. A sign-in ends
108
+ after 90 days unused and 365 days at most. `/account` lists **Connected
109
+ sessions** and revokes them. It works over SSH (device authorization, no
110
+ local callback). API keys keep working, and a `token` option or
111
+ `MEMORY_TOKEN` still wins.
112
+ - Gateway: `/oauth/device/code`, `/oauth/token`, `/oauth/revoke`, `/connect`
113
+ and `/api/connect/*` (`deploy/auth/connect.mjs`); tables `connect_device`,
114
+ `connect_grant` and `connect_token` in the auth database, created at start
115
+ and by `--migrate`; `CONNECT_ACCESS_TTL_SECONDS`, `CONNECT_IDLE_DAYS`,
116
+ `CONNECT_MAX_DAYS`, `CONNECT_RATE_LIMIT_ADDRESS_MAX`. No new secret.
117
+ `scripts/revoke-user-keys.mjs` ends a user's OpenCode sign-ins too.
118
+ - Security review fixes before release: the person **types** the code (no
119
+ prefilled link) under a plain warning, with the device's label shown as
120
+ unverified beside the request's time and address; code entry is limited
121
+ before the lookup, per user and per address; a retried refresh gets the
122
+ same successor (sealed under the spent token), so a sign-in never forks and
123
+ a lost response no longer ends it; `/oauth/*` has its own rate-limit
124
+ buckets; a user control disables or removes loses every sign-in on the next
125
+ refresh or request; user codes are stored as an HMAC.
126
+ - Second review: code entry limits every attempt per person (a lookup and its
127
+ approval are one) and only misses per address, both configurable, so an
128
+ office behind one address is not limited; a replay is allowed only within
129
+ `CONNECT_REPLAY_SECONDS` (120) of the spend and 3 times per sign-in per day,
130
+ anything else ends the sign-in; connect writes on its own connection to
131
+ `auth.db`, so it no longer fails inside, or joins, a Better Auth
132
+ transaction.
133
+
134
+ ### Changed
135
+
136
+ - **The console keeps record ids out of the main text.** A memory, key or
137
+ sign-in id is in a small "Details" disclosure per item, and dialogs and
138
+ toasts use words ("1 newer memory that replaced it", "your message from 9
139
+ Nov"). The forget dialog's warning is one sentence; the full, honest
140
+ explanation of what stays is in a "What stays, and why" disclosure. The same
141
+ two patterns apply to profile erase, page delete and source unbind.
142
+ - With no credential, the tools say to run `/connect` and choose Memory, or
143
+ set a key.
144
+
145
+ - **Console writes made with a session cookie need a CSRF token**, as well
146
+ as JSON and the gateway's Origin: `x-csrf-token` from
147
+ `GET /api/console/csrf` (`403 csrf_token_invalid` without it). API-key
148
+ callers are unchanged. Mission Control sends it.
149
+ - **Mission Control's styles hold no literal colours**: its glows, tints and
150
+ gradients are `color-mix` over the theme's semantic tokens, so a theme
151
+ restyles every view. Its old dark look remains the fallback when no theme
152
+ loads. Under a theme the categorical violet and orange collapse onto the
153
+ accent and warning tokens.
154
+ - The theme checker also checks `--success` on `--success-ground` (17 text
155
+ pairs).
156
+
157
+ ### Fixed
158
+
159
+ - **A held team write's dialog shows the whole text.** The review preview and
160
+ list clipped what a decision will write at 2,000 characters while accept
161
+ wrote all of it. The dialog now shows the full body in a scrollable region
162
+ with its character count, which can be focused when it is longer than the
163
+ region, and says "Scroll to read all N characters."
164
+ - **A CSRF token with a non-ASCII character is a 403, not a 500.** The token
165
+ is compared by bytes. `console-write-paths.md` is corrected about
166
+ `runtime.controlCall` (Memories' forget uses it for two core searches, reads
167
+ only) and about revoking copies (the cell's own rule is the guard).
168
+ - **The sealed Memory page's tab row wraps** (#51). Six tabs ran off the
169
+ edge at 390 px (and at larger text); the row now wraps, with the selected
170
+ tab's indicator and the row's border kept right. The Overview's detail list
171
+ no longer clips its values at larger text. `shots:views` now measures it
172
+ at 390 px, in light and night, at doubled text.
173
+ - **"Mark done" no longer shows a record id** (#52). The message reads
174
+ `Mark 'Send the Q4 numbers' as done.` Only when another open commitment
175
+ has the same words does it add the due date, then the owner, then the
176
+ trigger; only for a true duplicate does it keep the id. One helper
177
+ (`views/done-message.js`) serves Commitments and the Memory page. The
178
+ `mem.usage` skill now says to find a commitment by its words with `list`
179
+ and to ask when two match.
180
+ - **Home says "Memory can't be reached just now" when it is only that** (#53).
181
+ `memory.overview` has an optional `state` when `connected` is false:
182
+ `unconfigured`, `refused` or `unreachable`. The Home tile and the Memory
183
+ page's Overview tell them apart: unreachable shows the reason and **Try
184
+ again**, with no Settings instruction; refused says the key was refused.
185
+
186
+ ## [0.9.4] - not released
187
+
188
+ Release gate: VOID (`core-forget` failed one of three attempts, a safety item), not released; its changes ship in 0.9.5.
189
+
190
+ **0.9.4 ships 0.9.3's changes** (below; 0.9.3 itself was not released after its gate failed on one safety attempt, see [evals/results/baseline-2026-11-10-0.9.3-README.md](evals/results/baseline-2026-11-10-0.9.3-README.md)), plus these fixes from an independent review of 0.9.3's write retries
191
+ ([docs/design/records-idempotency.md](docs/design/records-idempotency.md)).
192
+ The records service is as in 0.9.3's notes: deploy it first.
193
+
194
+ Also: the backfill script drives the core's operator routes (`--source api --service-id`), and the extraction gate's judge can run through the cell's LLM shim (rules `.3`).
195
+
196
+ ### Fixed
197
+
198
+ - **Captured turns carry no absolute local path.** Capture already redacted
199
+ credential-shaped values; it now also replaces macOS, Linux, Windows (drive
200
+ and UNC) and `~` paths with `<path>/<file name>` (`<path>` when the last part
201
+ is a user's name) before a turn leaves the process, so they reach neither L0
202
+ nor the extraction model. The backfill's gate found extraction copying such
203
+ paths into memories (8 of 79 in a sample), against Memory's own rule. The
204
+ derived core (opencode-mem-deploy) applies the same rules to L1 output, which
205
+ also covers turns already in L0; `test/fixtures/redaction-vectors.json` is
206
+ shared by both.
207
+ - **Write retries happen when the service is slow.** 0.9.3 asked
208
+ `space.stats` (1-second timeout) before every retry; after a write timed out
209
+ at 10 seconds that ask timed out too, and no retry was sent. A retry now
210
+ relies on the cached replay capability, with no fresh ask. The ask before
211
+ the first write to a space is unchanged.
212
+ - **A retry the service did not key is never reported as success.** Every
213
+ keyed answer carries `keyed: true`. A retry answered without it (records
214
+ rolled back to 0.9.2 while the plugin runs) drops the cached capability and
215
+ is reported as `MEMORY_POSSIBLY_DUPLICATED`: "possibly applied twice: check
216
+ before writing again".
217
+ - **Identical calls in one message stay distinct writes.** The occurrence
218
+ count behind idempotency keys was one 5,000-entry list for the process, so
219
+ after 5,000 other calls an identical call in the same message could reuse
220
+ the first key and be replayed instead of written. It is now kept per
221
+ message (up to 10,000 messages, least recently used first). Keys are
222
+ derived as before.
223
+
224
+ ### Changed
225
+
226
+ - **Docs:** snapshots taken by a pre-0.9.3 records service (0.9.1 or 0.9.2)
227
+ can't be installed on 0.9.3; take them on 0.9.3. The 0.9.3 runbook's
228
+ rollback now says to stop or drain the plugins, and wait for writes in
229
+ flight, before a records downgrade
230
+ ([docs/deployment.md](docs/deployment.md#upgrade-to-093-idempotent-records-writes)).
231
+
232
+ ## [0.9.3] - not released
233
+
234
+ Release gate: FAIL (safety, one attempt), not released; its changes ship in 0.9.4.
235
+
236
+ 0.9.3 adds the first of Jelly's requests (#43–#49) as generic Memory features,
237
+ safe write retries, secrets from files, and the extraction backfill's tooling.
238
+ Plan: [docs/design/jelly-requests-0.9.3-0.10.md](docs/design/jelly-requests-0.9.3-0.10.md).
239
+ Acts from a host's UI (keep, edit, forget, erase, snooze, decide) wait for
240
+ the verified-caller grants of 0.10
241
+ ([docs/design/adr-verified-caller-grants.md](docs/design/adr-verified-caller-grants.md)).
242
+
243
+ **Deploy order: the records service first, on every cell, then the plugin.**
244
+ The records service is changed in this release. Its space files keep their
245
+ `schema_version`, so either part can be rolled back alone. Control is changed
246
+ only to read secrets from files; deploy it in any order.
247
+
248
+ ### Added
249
+
250
+ - **Recent memories across spaces (#47).** `memories.recent` covers every
251
+ space the caller can read; each row carries `space {id, name}`. Membership
252
+ is checked per space; a space that fails to load is named in `incomplete`.
253
+ - **Overdue commitment notices (#48).** One Inbox item per overdue commitment,
254
+ keyed `commitment:<id>`, updated in place each day, and cleared when the
255
+ commitment is closed or its due date moves to the future. It is published
256
+ only when the host asks for its Inbox; OpenCode keeps its Due list.
257
+ - **Your profile (#46).** The `profile.read` view and
258
+ `mem_spaces({ action: "profile" })`: the persona and scenarios Memory holds,
259
+ bounded and labelled as data. Erasing it comes with 0.10's grants.
260
+ - **Proposed memories on reads (#45).** Memories held for review read back as
261
+ `status: "proposed"`, with `source` and `stated_by`.
262
+ - **Extraction backfill tooling (#44).** `scripts/backfill-extraction.mjs`
263
+ counts never-extracted conversation groups (the dry run is the default and
264
+ writes nothing, not even an audit row) and re-triggers them in canary and
265
+ batch runs that stop themselves. `scripts/eval/extraction-gate.mjs` is the
266
+ quality gate, with thresholds registered before any run. See
267
+ [docs/operations/backfill.md](docs/operations/backfill.md).
268
+ - **The release gate's call-budget rule, version 2 (#14).** The core pair
269
+ compares over-budget attempts with the baseline's instead of rejecting any
270
+ single overrun. It applies to runs made after 2026-11-10 11:18 UTC; every
271
+ past verdict stands. See [docs/evals/README.md](docs/evals/README.md).
272
+ - **Idempotent records writes (#40).** `records.put`, `records.revise`,
273
+ `records.append`, `records.move` and `records.delete` take an
274
+ `idempotency_key`. The service applies a key once per user and agent in a
275
+ space, and answers a repeat with the original result, even when the record
276
+ has changed or gone since. It looks the key up before any other check,
277
+ commits the receipt in the write's own transaction, and keeps ids and
278
+ versions, never content. Receipts expire after 24 hours
279
+ (`RECORDS_RECEIPT_TTL_HOURS`) and are capped per space
280
+ (`RECORDS_RECEIPT_MAX`). A retry older than the ledger can vouch for is
281
+ refused (`idempotency_expired`), not applied again. `space.stats` and
282
+ `/health` advertise `idempotent_replay`. Design:
283
+ [docs/design/records-idempotency.md](docs/design/records-idempotency.md).
284
+ - **The plugin retries a lost write with the same key.** The plugin keys a
285
+ write only for a records service that advertises replay for that method. It
286
+ asks again before each retry. It retries `recordsWriteRetries` times
287
+ (default 2, `MEMORY_RECORDS_WRITE_RETRIES`) and reports the service's
288
+ answer. Keys come from the tool call's session, message and call ids, so two
289
+ calls never share one. An older service gets no key, and an unknown outcome
290
+ is reported as in 0.9.2 (#37).
291
+ - **Secrets from files (#39).** Control (`CONTROL_ADMIN_TOKEN`,
292
+ `CONTROL_SERVICE_TOKEN`, `CONTROL_DB_URL`, `CONTROL_RECORDS_CHECKS`,
293
+ `CONTROL_RECORDS_DEFAULT_KEY`, `CONTROL_KNOWLEDGE_KEY`, `CONTROL_CORE_KEY`)
294
+ and records (`RECORDS_API_KEY`, `RECORDS_HELD_RECEIPT_KEY`,
295
+ `RECORDS_CORE_KEY`, `RECORDS_LLM_KEY`) read `<NAME>_FILE`. The file wins, is
296
+ read once at start, and is never logged. See
297
+ [docs/deployment.md](docs/deployment.md#service-secrets-from-files). The
298
+ deploy repository's switch to file mounts is a separate change.
299
+
300
+ ### Changed
301
+
302
+ - Space snapshots leave out keyed-write receipts, and the content checksum
303
+ skips their table.
304
+ - Records housekeeping also prunes expired receipts and the 0.9.1 create-ledger
305
+ rows whose record is gone.
306
+
307
+ ### Fixed (from the independent review of #40 and #39)
308
+
309
+ - **No double apply at the receipt cap.** The cap no longer evicts receipts
310
+ still inside their window (with a cap of 3, a slow retry and an age-0
311
+ re-send were applied twice). At the cap the service prunes expired receipts,
312
+ then refuses the new keyed write with 429 `idempotency_capacity`, which the
313
+ plugin reports as "not saved". Receipts are kept an hour past the window, so
314
+ a retry the window accepts always finds its receipt. Inserts keep a count
315
+ instead of counting the table.
316
+ - **Keys survive the real call id.** OpenCode 2.2.6 passes `context.id`, but
317
+ under Code Mode it is the outer `execute` call's id, shared by every tool
318
+ call in the script. Keys, held-write keys included, now also use the tool,
319
+ a digest of its arguments and that call's occurrence index in the message:
320
+ identical calls in one script are two writes, and a call re-sent after a
321
+ restart replays.
322
+ - **`*_FILE` everywhere in control (#39).** The default records placement check
323
+ and the CLI argument parsers read secrets through the `*_FILE`-resolved
324
+ environment; before, they read `process.env` and missed
325
+ `CONTROL_RECORDS_CHECKS_FILE`. The routines' keys read their `_FILE` too.
326
+ - The plugin remembers a service that replays for the life of the process, and
327
+ forgets it when a keyed answer lacks the new `keyed: true` marker. Its
328
+ `space.stats` ask has a 1-second timeout and no retry.
329
+
6
330
  ## [0.9.2] - 2026-11-10
7
331
 
8
332
  Release gate: [evals/results/baseline-2026-11-10-0.9.2-README.md](evals/results/baseline-2026-11-10-0.9.2-README.md): **FAIL on the core pair's call-budget rule** (one attempt over budget; 0 new failures, every safety item passes), shipped as a recorded decision. This is a plugin-only release. The records, control and
package/README.md CHANGED
@@ -114,8 +114,18 @@ in the package; deploy it from this repository.
114
114
  ## Plugin configuration
115
115
 
116
116
  For a control-plane deployment, point `controlURL` at the **public gateway
117
- origin**, not at the internal control service. `token` is the teammate's Better
118
- Auth API key.
117
+ origin**, not at the internal control service. Then sign in once:
118
+
119
+ 1. Run `/connect` in OpenCode and choose **Memory**.
120
+ 2. Open the link OpenCode shows and sign in with your work Google account.
121
+ 3. Type the code OpenCode shows (such as `BCDF-GHJK`) and approve. Approve only
122
+ a sign-in you just started yourself: never a code someone sent you.
123
+
124
+ OpenCode stores the sign-in and renews it by itself: you never paste a key.
125
+ A sign-in ends after 90 days without use (then `/connect` again), and you can
126
+ revoke it on Memory's `/account` page under **Connected sessions**. It works
127
+ over SSH and on remote hosts too: open the link on any machine. Design:
128
+ [docs/design/plugin-sign-in.md](docs/design/plugin-sign-in.md).
119
129
 
120
130
  ```jsonc
121
131
  {
@@ -123,10 +133,7 @@ Auth API key.
123
133
  {
124
134
  "package": "/opt/opencode-mem",
125
135
  "options": {
126
- "baseURL": "https://memory.example.com/core",
127
- "knowledgeURL": "https://memory.example.com/knowledge",
128
136
  "controlURL": "https://memory.example.com",
129
- "token": "{env:MEMORY_TOKEN}",
130
137
  "agent": "auto",
131
138
  "captureVisibility": "private"
132
139
  }
@@ -135,12 +142,17 @@ Auth API key.
135
142
  }
136
143
  ```
137
144
 
145
+ **Automation** (CI, a server with no browser, a script) keeps using an API key
146
+ from `/account`: set `token` (for example `"{env:MEMORY_TOKEN}"`). A key set
147
+ this way wins over a `/connect` sign-in. `/connect` needs OpenCode 2.2 or
148
+ newer; on older hosts use a key.
149
+
138
150
  | Option | Default | Meaning |
139
151
  |---|---|---|
140
152
  | `baseURL` | `<controlURL>/core`; without a gateway `http://127.0.0.1:8420` | Memory core or gateway `/core` URL |
141
153
  | `knowledgeURL` | `<controlURL>/knowledge`; without a gateway `baseURL` | Wiki / code-graph service |
142
154
  | `controlURL` | `MEMORY_CONTROL_URL`; inside Jelly the Jelly account's memory origin | Public gateway origin for spaces, context, and turn capture (`/v1/capture`) |
143
- | `token` | `MEMORY_TOKEN`; inside Jelly a Jelly token, then the pasted key | Better Auth API key. Order: [Running inside Jelly](#running-inside-jelly) |
155
+ | `token` | `MEMORY_TOKEN`; else the `/connect` sign-in; inside Jelly a Jelly token, then the pasted key | Better Auth API key, for automation. Without it, sign in with `/connect` → Memory. Order: [Running inside Jelly](#running-inside-jelly) |
144
156
  | `capture` | `true` | Capture completed turns. `false` keeps the tools and captures nothing |
145
157
  | `captureVisibility` | `private` | Completed turns stay personal unless explicitly shared. `team` writes a turn to the session's bound shared space; the gateway decides, and a session with no shared binding keeps the turn private |
146
158
  | `captureSubagents` | `false` (`MEMORY_CAPTURE_SUBAGENTS`) | Capture and pin subagent (child) sessions. Off: a child's brief is never stored as a user turn, and the child gets the protocol but not the pinned block |
@@ -150,14 +162,19 @@ Auth API key.
150
162
  | `collect` | `true` (`MEMORY_COLLECT`) | Collect from the person's bound sources on a timer while OpenCode runs; one process per machine, the holder of `stateDir/collector.lock`. Off: `mem_collect` and `/mem-collect` still collect on request |
151
163
  | `collectEveryMinutes` | `30` | Minutes between collections, 5 to 1440 |
152
164
  | `recordsWriteTimeoutMs` | `10000` (`MEMORY_RECORDS_WRITE_TIMEOUT_MS`) | Timeout in milliseconds for records writes; reads still use `timeoutMs` (2000 ms by default) |
165
+ | `recordsWriteRetries` | `2` (`MEMORY_RECORDS_WRITE_RETRIES`) | Retries of a records write whose response was lost, with the same idempotency key, 0 to 5; only to a records service that advertises replay |
153
166
  | `stateDir` | `~/.local/state/opencode-mem` | Spool, claims, the collector's lock and status, materialised skills, log |
154
167
  | `debug` | `false` | Add DEBUG lines to the log and mirror every line to stderr. Leave it off in daily use |
155
168
  | `debugFile` | `stateDir/debug.log` | Plugin log. INFO, WARN, and ERROR are always written; mode 0600; rotates at 5 MB into `debug.log.1`. Query, prompt, and memory text are never logged |
156
169
 
157
170
  If a records write times out, resets or returns an invalid response, its outcome
158
- is unknown. Check the records before you retry. Retrying can create duplicates.
159
- The records service is unchanged in 0.9.2. Idempotent retries are planned for
160
- 0.9.3.
171
+ is unknown. Since 0.9.3 the plugin retries such a write itself, with the same
172
+ idempotency key, against a records service that advertises replay (0.9.3 and
173
+ later): the service applies the write once and answers the original result.
174
+ Only when every retry fails, or the records service is older, does a tool
175
+ answer that the outcome is unknown: check the records before you retry, since a
176
+ new call is a new write. Design:
177
+ [docs/design/records-idempotency.md](docs/design/records-idempotency.md).
161
178
 
162
179
  There is no team, private-team, user-key, or admin-URL setting. A control-plane
163
180
  deployment gets every container from the resolved space context. Without
@@ -368,7 +385,7 @@ only this plugin's read-only RPC, and only for the agent it is shown for.
368
385
  |---|---|---|---|
369
386
  | `home` "Memory" | Home tile, small | Whether conversations are remembered, and how many memories are kept | `rpc`: `memory.overview` |
370
387
  | `commitments` "Commitments" | Home tile, small | Open commitments, overdue first, at most eight: what, when ("Overdue since Tue 3 Nov", never colour alone), and who ("You", "Your agent", "Waiting on Kwame"), each with **Mark done…** | `rpc`: `commitments.list`, `open-agent` |
371
- | `memory` "Your memory" | This plugin's card in Settings → Plugins | Five tabs: **Overview** (what memory is, the sign-in in use, the address, Remember conversations, health, counts), **Commitments** (open ones with Mark done, and those closed recently), **Spaces**, **Wiki** (browse and read), **Recent** (the newest 100 memories, with Forget) | `data`, `rpc`: the seven 0.8 methods, `open-agent` |
388
+ | `memory` "Your memory" | This plugin's card in Settings → Plugins | Six tabs: **Overview** (what memory is, the sign-in in use, the address, Remember conversations, health, counts), **Commitments** (open ones with Mark done, and those closed recently), **Spaces**, **Wiki** (browse and read), **Recent** (the newest 100 memories across your spaces, with Forget on your own), **About you** (what Memory holds about you: the persona and scenarios, as data) | `data`, `rpc`: the seven 0.8 methods and `profile.read`, `open-agent` |
372
389
  | `today` "Today in memory" | Home tile, medium | The newest daily journal's summary line, how many proposals wait for review, what is due today | `rpc`: `journal.list`, `review.list`, `commitments.list` |
373
390
  | `journal` "Journal" | Home tile, large | The `journal/…` pages (daily, weekly, monthly), newest first; one page with its citations, sources and footer; "Edited by you" | `rpc`: `spaces.list`, `journal.list`, `journal.read`, `pages.read` |
374
391
  | `review` "Review" | Home tile, large | Proposals waiting for review: what each would do, its target, why it waits, its evidence, and who said it; **Accept…**, **Edit…**, **Reject…** | `rpc`: `spaces.list`, `review.list`, `open-agent` |
@@ -385,7 +402,8 @@ sees it:
385
402
  |---|---|---|
386
403
  | `memory.overview` | `mem_status` | The credential source, the address, capture as this engine runs it, health, the personal space and its counts |
387
404
  | `spaces.list` | `mem_spaces` | `GET /v1/spaces` |
388
- | `memories.recent` | `mem_recall` | The personal space's newest records of kind `memory` (`records.list`), 50 a page, two pages; since 0.9, no longer the core's atoms |
405
+ | `memories.recent` | `mem_recall` | The newest memories (records of kind `memory`, and those held for review as `status: "proposed"`) of every space the person can read (`records.list`, `review.list`), each row naming its space; 50 a page, two pages; a space that cannot be read is named in `incomplete`; since 0.9, no longer the core's atoms |
406
+ | `profile.read` | `mem_recall` | What Memory holds about the person: the persona and the scenarios under it, bounded and labelled as data (`core/read`, `scenario/ls`, `scenario/read`) |
389
407
  | `wiki.list`, `wiki.pages`, `wiki.read` | `mem_wiki` | The personal space's wikis, a wiki's pages, one page (at most 48,000 characters); never the reserved "Memory records" wiki |
390
408
  | `commitments.list` | `mem_commitments` | The personal space's commitments (records of kind `commitment`): open ones overdue first, or those closed recently |
391
409
  | `journal.list`, `journal.read` | `mem_page` | The `journal/…` pages, newest first, and one of them (`records.list`, `records.get`) |
@@ -393,7 +411,7 @@ sees it:
393
411
  | `graph.links` | `mem_page` | The neighbourhood of a page, one or two steps out (`records.links`) |
394
412
  | `review.list` | `mem_spaces` | The proposals waiting for review (`review.list`) |
395
413
 
396
- Fourteen methods, all read-only. A server without the records service (503
414
+ Sixteen methods, all read-only (`inbox.list`, which the Inbox reads, is described in [In Jelly](docs/jelly.md)). A server without the records service (503
397
415
  `records_unavailable`) gets one sentence in every view that reads records.
398
416
 
399
417
  **Views ask for the person who opened them (Jelly 0.3.3 and later; 0.8.3).**
@@ -33,7 +33,7 @@ inside `execute`, with the same arguments.
33
33
  | `mem_commitments` | `action` | read-only: `list`; writes: `add`, `update`, `delete` | `id`, `what`, `owner`, `due`, `trigger`, `state` (`open`, `done`, `cancelled`, `all`), `project`, `link`, `due_before` | Track things someone will do, with a due date or a trigger. |
34
34
  | `mem_wiki` | `action` | read-only: `list`, `search`, `read`, `status`; writes: `create`, `write`, `append`, `delete` | `query`, `knowledge_id`, `wiki_id`, `name`, `filename`, `content`, `ingest`, `ref`, `confirm`, `path`, `visibility` (`auto`, `private`, `team`), `type` (`wiki`, `code-graph`, `all`), `space` | Search and read documents: uploads, repositories and the pages synthesised from them. |
35
35
  | `mem_share` | `action` | read-only: `list`; writes: `grant`, `revoke`, `transfer`, `copy` | `path`, `ids`, `to`, `role` (`viewer`, `editor`), `expires`, `space`, `rationale`, `grant_id` | Only when the person asks: grant a page or folder to others, or copy private memories into a shared space. |
36
- | `mem_spaces` | `action` | read-only: `current`, `list`, `members`, `access`, `health`; writes: `sources`, `review` | `space`, `bind`, `unbind`, `confirm`, `decide`, `limit` | See where memory lives and what flows into it: spaces, members, access, health, sources and review. |
36
+ | `mem_spaces` | `action` | read-only: `current`, `list`, `members`, `access`, `health`, `profile`; writes: `sources`, `review` | `space`, `bind`, `unbind`, `confirm`, `decide`, `limit` | Where memory lives and what flows in: spaces, members, access, health, sources, review. |
37
37
  | `mem_collect` | none | none | `source`, `wait` | Collect new events from the person's bound sources (mail, chat, meetings) into Memory now. |
38
38
 
39
39
  `ingest` and `cursor` belong to the collector: never call them. Deprecated names, kept until 0.10: `forget` (mem_revise forget), `promote` (mem_share copy or revoke), `status` (mem_spaces health), `grants` (mem_spaces access), `members` (mem_spaces members).