@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.
- package/CHANGELOG.md +429 -0
- package/README.md +114 -61
- package/docs/agent-protocol.md +67 -177
- package/package.json +1351 -98
- package/skills/mem.pages/SKILL.md +143 -0
- package/skills/mem.sharing/SKILL.md +82 -0
- package/skills/mem.sources/SKILL.md +93 -0
- package/skills/mem.usage/SKILL.md +118 -492
- package/src/backend/records.js +285 -0
- package/src/bootstrap.js +49 -45
- package/src/call-shapes.js +41 -10
- package/src/collector-lock.js +162 -0
- package/src/collector-service.js +441 -0
- package/src/collector.js +381 -0
- package/src/commands.js +3 -3
- package/src/config.js +12 -1
- package/src/curation.js +1 -1
- package/src/permissions.js +18 -2
- package/src/protocol.js +29 -20
- package/src/recall.js +104 -27
- package/src/records-store.js +280 -120
- package/src/records.js +63 -11
- package/src/runtime.js +23 -14
- package/src/skills.js +44 -18
- package/src/sources.js +58 -0
- package/src/spaces.js +93 -10
- package/src/tools/aliases.js +163 -0
- package/src/tools/commitments.js +12 -9
- package/src/tools/index.js +88 -19
- package/src/tools/ingest.js +277 -0
- package/src/tools/knowledge.js +6 -1
- package/src/tools/memory.js +640 -210
- package/src/tools/page.js +411 -0
- package/src/tools/recall.js +363 -112
- package/src/tools/records-kit.js +142 -0
- package/src/tools/share.js +1012 -0
- package/src/tools/shared.js +8 -1
- package/src/tools/spaces.js +431 -143
- package/src/tools/status.js +87 -58
- package/src/tools/wiki.js +2 -2
- package/src/views/contracts.js +273 -3
- package/src/views/records-reads.js +675 -0
- package/src/views/rpc.js +17 -100
- package/src/views/shape.js +61 -0
- package/views/commitments.html +4 -0
- package/views/graph.html +753 -0
- package/views/home.html +11 -5
- package/views/journal.html +621 -0
- package/views/memory.html +7 -1
- package/views/pages.html +636 -0
- package/views/review.html +406 -0
- 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)).
|