@joe-broadhead/opencode-mem 0.8.2 → 0.8.4

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,142 @@
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.8.4] - 2026-11-08
7
+
8
+ Release gate: [evals/results/baseline-2026-11-08-0.8.4-README.md](evals/results/baseline-2026-11-08-0.8.4-README.md).
9
+
10
+ The P0 fixes from the 0.8.3 tool walkthrough against production
11
+ ([docs/design/memory-tools-v1.md](docs/design/memory-tools-v1.md) §3 and §12). Finding
12
+ numbers are the design document's.
13
+
14
+ ### Fixed
15
+
16
+ - **Source files with a folder are refused before anything is asked**
17
+ (finding 1). The hub's `raw/write` creates `raw/sources/` but never a folder
18
+ under it (`rawWriteMany`, read from the image), and no route or parameter
19
+ does: `page/write` creates folders but writes locked generated pages outside
20
+ the source and ingest model. `projects/<slug>.md` failed with `ENOENT` after
21
+ the person approved it. `mem_wiki` now refuses a nested name with the flat
22
+ name to use (`project-harbour.md`, `person-ama.md`); the descriptions, skill
23
+ and docs use flat names. `npm run wiki:ingest` uploads nested files under
24
+ flat names and refuses two that flatten to one name.
25
+ - **A write to an ingesting wiki is refused before the ask** (finding 2). The
26
+ wiki's status is read first; while it is `processing` the answer is
27
+ `MEMORY_WIKI_BUSY` with the next step (retry when ready, or batch with
28
+ `ingest: false` and `ingest: true` on the last write). The hub's `409` and
29
+ `ENOENT` refusals map to `MEMORY_WIKI_BUSY` and `MEMORY_WIKI_NO_FOLDERS`
30
+ instead of "check the call against the tool's description", and never repeat
31
+ the hub's disk path. The approval is asked only once the write can run. The
32
+ skill's own page-update example batched wrong; it now batches.
33
+ - **`remember` answers with the stored turn's id** (finding 3). The answer
34
+ keeps its "stored N message(s)" head and adds the turn id (`msg-…`), that the
35
+ atom id (`m_…`) appears after extraction through `mem_recall`, and the forget
36
+ call that removes it before then. `supersedes` documents the core's `m_…`
37
+ atom ids (the core mints `m_<ms>_<hex>`; `atomic/delete` takes any string id)
38
+ and refuses a turn id before writing. A supersede says plainly that the old
39
+ atom is removed now and the new one is recallable after extraction.
40
+ - **`promote` no longer re-binds the session** (finding 7). An explicit
41
+ `space` applies to that share or revoke only: neither the control context
42
+ call nor the data-plane calls carry the session with it.
43
+ - **Status-shaped writes are refused as the description says** (finding 8):
44
+ a `Status:`/`Progress:` label, a `WIP`/`In progress` line opener, "is half
45
+ (mostly, nearly) done", "N% done/complete", "is under way". Rules and facts
46
+ that mention the words ("status 403", "never ship half done migrations", "an
47
+ error budget of 0.1%") are still stored.
48
+ - **`wiki` description and errors** (findings 10, 11): no promise of a "My
49
+ knowledge" wiki before `create`; a write with no wiki says to create one,
50
+ with the call; `read` no longer lists "pages: none" while the wiki ingests,
51
+ and `status` keeps the wiki's own page count.
52
+ - **One delete rule** (finding 12): the person's explicit request is consent;
53
+ the agent asks first when it proposes the deletion. `forget`'s description,
54
+ the skill and the protocol now agree.
55
+ - **Compact search output** (finding 11): one line per hit (path, title, a
56
+ short snippet) and its links (`→ entities/ama`), no raw JSON, inside the
57
+ character budget.
58
+
59
+ ### Changed
60
+
61
+ - **`wiki` defaults to the session's space** (finding 12), as `recall`'s
62
+ `auto`: a shared space bound to the session (a team write that asks), else
63
+ the personal space (no ask). `visibility` takes `auto`, `private`, `team`.
64
+ Local mode has no shared space, so a write without `visibility` is private
65
+ there and no longer asks.
66
+ - The namespace call shape and the skill say `write` and `append` need
67
+ `filename`; `type` has a description.
68
+
69
+ ### Added
70
+
71
+ - **`mem_wiki` `delete`** (finding 6): a source file (`filename`), a generated
72
+ page (`ref`), or a whole wiki (`wiki_id` alone). It previews without
73
+ `confirm`, always asks with `confirm: true`, and reads the deletion back. A
74
+ whole wiki in a control-plane space goes through
75
+ `DELETE /v1/spaces/:id/resources/:resource_id`, so its catalog row and grants
76
+ go with it.
77
+ - **A new approval action, `wiki.delete`**, in `jelly.asks` and in the
78
+ plugin's default rules (`ask`). Jelly's default rules should set it to `ask`.
79
+ - **Gateway:** `wiki/delete`, `wiki/page/rm` and `wiki/raw/rm` are allowed
80
+ for owners, admins and editors (never viewers). `wiki/delete` is answered
81
+ with the resource delete (control's check, the content with a read-back, the
82
+ catalog row), so a data-plane delete leaves no dangling catalog row; another
83
+ editor than the owner is refused (`resource_delete_forbidden`), an agent
84
+ credential too (`agent_delete_forbidden`). The code graph's `callers`,
85
+ `callees` and `impact` are reads.
86
+ - The stub mirrors the hub: nested raw writes fail with `ENOENT`, ingestion
87
+ can take time (`MEM_STUB_INGEST_MS`, `POST /debug/ingest`) with the
88
+ processing lock, and `wiki/raw/rm` and `wiki/page/rm` are served.
89
+
90
+ ## [0.8.3] - 2026-11-07
91
+
92
+ Memory's views ask for the person who opened them (Jelly's resource-token
93
+ contract v1.5 §6.1, Jelly 0.3.3). Not published yet: it is published from its
94
+ own `v0.8.3` tag by `.github/workflows/release.yml`.
95
+
96
+ ### Changed
97
+
98
+ - **A view call asks as its person.** Every method Memory's views call
99
+ (`memory.overview`, `spaces.list`, `memories.recent`, `wiki.list`,
100
+ `wiki.pages`, `wiki.read`, `commitments.list`) declares an optional string
101
+ `jellySpeaker` in its input, in `package.json`'s `jelly.rpc` and in the
102
+ schema the plugin registers with the engine (`src/views/contracts.js`). A
103
+ Jelly host of v1.5 or later fills it with a speaker id naming the person
104
+ whose device made the call. The handler strips it from the input
105
+ (`splitSpeaker` in `src/views/rpc.js`) and runs the read in `asView(id)`
106
+ (`src/credentials.js`): every request of that call carries
107
+ `token("memory", { session: id })`, asked once per call. On a shared agent a
108
+ member's view now shows the member's own memory, and the owner's view works
109
+ after a plugin's turn.
110
+ - **Kept for the call only.** A view call's token and refusal live in the
111
+ call's scope and go with it: never in the 64-session cache or its refusal
112
+ hold, never reused by a later call, the skill mirror, background work or a
113
+ spool replay. The id is never sent to the gateway, logged (a view call's
114
+ refusal is logged as `view: true`), stored or spooled; a write spooled inside
115
+ a view call would record the account its token named and replay under the
116
+ session rules, never with the id.
117
+ - **An unlinked person.** When Jelly refuses a view call with `not_enrolled`
118
+ and the detail `not_signed_in`, Jelly is asked before any request, the call
119
+ uses no credential (not the pasted key, not the owner's or another session's
120
+ token) and sends nothing, and the view answers "Memory is unavailable: you
121
+ have not linked a Jelly account on this host." Other refusals fall back as
122
+ for a session; `access_denied` does not.
123
+ - **Unchanged without the id:** a Jelly before 0.3.3 and stock OpenCode send no
124
+ `jellySpeaker`, and a view asks `token("memory")` with no options, exactly as
125
+ in 0.8.2. A malformed id runs the call the same way.
126
+ - **The declaration grows by one optional input property per method** and asks
127
+ for nothing more: no tool, permission, resource, sign-in, view or grant
128
+ changes, and a method's `permission` and `label` are unchanged, so Jelly's
129
+ declaration refresh (DECL-REFRESH) applies it at once and puts nothing under
130
+ Changes to review.
131
+
132
+ ### Added
133
+
134
+ - `test/view-speaker.test.js`: the eight Memory tests of the VIEW-SPEAKER
135
+ spec, against the real control plane and gateway: a view call asks with its
136
+ id once; without one it asks as 0.8.2; Sam's and Ana's concurrent calls keep
137
+ their own tokens; no view token outlives its call; an unlinked person's call
138
+ sends nothing; the id never reaches a request, the log or a stored record;
139
+ actions (none declared) and the spool; and the declaration's optional
140
+ `jellySpeaker` on every method, never required.
141
+
6
142
  ## [0.8.2] - 2026-11-06
7
143
 
8
144
  A Jelly token per chat, and no fallback for a speaker with no linked account
package/README.md CHANGED
@@ -193,9 +193,9 @@ is still captured with its own speaker's token; a spooled turn is replayed only
193
193
  while the chat's token names the person who spoke it. A turn with no user
194
194
  message (a wake, a routine) keeps the cached token. Tokens are kept per session, for at most 64 sessions (the least
195
195
  recently used goes first), and a session's is dropped when the session is
196
- deleted. Work that belongs to no chat (the skill mirror, Memory's views) asks
197
- `token("memory")` as before, which Jelly answers with the agent owner's token
198
- while the agent is private. A Jelly older than members (0.3.2) refuses the
196
+ deleted. Work that belongs to no chat (the skill mirror, and Memory's views on
197
+ a Jelly before 0.3.3) asks `token("memory")` as before, which Jelly answers
198
+ with the agent owner's token while the agent is private. A Jelly older than members (0.3.2) refuses the
199
199
  `session` option; the plugin then asks as before, one token for the agent,
200
200
  which on such a host is its owner's.
201
201
 
@@ -293,11 +293,13 @@ approval actions, with the space as the resource: `memory.remember`,
293
293
  Jelly's default rules (`agents/default/opencode.jsonc`) set all five to `ask`,
294
294
  so a person approves each write to a shared space. Private writes, the default,
295
295
  assert none of them; a forget still asks as `mem_forget`, so a team forget asks
296
- twice in Jelly. These five action names are a contract with
296
+ twice in Jelly. A wiki delete (0.8.4) asserts `wiki.delete` in every space,
297
+ private too; the plugin's own default rules set it to `ask` in OpenCode, and
298
+ Jelly's default rules need it too. These six action names are a contract with
297
299
  Jelly: do not rename one, or add one, without telling Jelly, or a team write
298
300
  runs without a prompt there.
299
301
 
300
- **`asks`.** The declaration lists the same five actions in `"asks"`, so Jelly
302
+ **`asks`.** The declaration lists the same six actions in `"asks"`, so Jelly
301
303
  can read from the plugin, not only from its own default rules, which run-time
302
304
  actions to ask a person about. Like `resources`, it is additive and not in
303
305
  `requires`: a Jelly that does not know the field leaves it out and still loads
@@ -349,6 +351,30 @@ sees it:
349
351
  | `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 |
350
352
  | `commitments.list` | `mem_commitments` | The personal space's commitments (the records wiki's `commitments.json`): open ones overdue first, or those closed recently |
351
353
 
354
+ **Views ask for the person who opened them (Jelly 0.3.3 and later; 0.8.3).**
355
+ A view is opened by a person on a device, not in a chat, so a view call has no
356
+ session of its own. Every method's input therefore names an optional string,
357
+ `jellySpeaker` (contract v1.5 §6.1). A Jelly of 0.3.3 or later sees it in the
358
+ declared schema and fills it with a short-lived speaker id, `view_…`, naming
359
+ the person whose device made that one call: the owner, a member with a linked
360
+ Jelly account, or a person with none. The handler takes it out of the input
361
+ before the read sees it and asks `token("memory", { session: <id> })` for that
362
+ call, so on a shared agent a member's view shows the member's own memory, and
363
+ a view still works after another plugin's turn. That token is kept for the
364
+ call only: never in the per-chat cache, never for a later call, the skill
365
+ mirror or the spool, and the id never reaches the gateway, the log or a stored
366
+ record. When Jelly answers `not_enrolled` with the detail `not_signed_in`, the
367
+ person who opened the view has not linked a Jelly account on this host: that
368
+ call uses no credential at all (not the pasted key, not the owner's or another
369
+ chat's token), sends nothing, and the view says "Memory is unavailable: you
370
+ have not linked a Jelly account on this host." Other refusals fall back as
371
+ for a chat. A Jelly before 0.3.3, or stock OpenCode, sends no `jellySpeaker`,
372
+ and a view then asks exactly as in 0.8.2. The id is optional and is never in
373
+ `required`; the schemas keep `additionalProperties: false`. Adding it asks for
374
+ nothing more: no tool, permission, resource or sign-in changes, so Jelly's
375
+ declaration refresh applies it with the release and puts nothing under
376
+ Changes to review.
377
+
352
378
  Every call is a read the tools already make, through the gateway with the
353
379
  credential chain above, so no gateway route is added for the views and the
354
380
  gateway scopes each one to the caller. A view never names a user, a space or
@@ -19,7 +19,7 @@ inside `execute`, with the same arguments.
19
19
  | `mem_recall` | `query` | Search atoms and turns; optional `task`, `visibility`, `limit`, `type`, `sources`, `space` |
20
20
  | `mem_remember` | `content` | One preference, constraint, decision, fact, or procedure; optional `kind`, `reason`, `supersedes`, `visibility`, `task`, `space` |
21
21
  | `mem_commitments` | `action` | Things to do, with a `due` date (`YYYY-MM-DD`) or a `trigger`: `list`; `add` (needs `what`); `update` and `delete` (need `id`). Private, never asks |
22
- | `mem_wiki` | `action` | `list`, `search`, `read`, `status`; `create`, `write`, `append` |
22
+ | `mem_wiki` | `action` | `list`, `search`, `read`, `status`; `create`, `write`, `append`, `delete` (previews unless `confirm: true`; always asks) |
23
23
  | `mem_forget` | `ids` or `match` | Delete atoms and turns by id, or erase a phrase from the persona and scenarios (preview, then `confirm`); irreversible |
24
24
  | `mem_promote` | `ids` + `rationale`, or `revoke` | Share private memory as a copy in a shared space, or take a share back |
25
25
  | `mem_status` | none | Backend health, scope, layer counts, spool |
@@ -28,9 +28,11 @@ inside `execute`, with the same arguments.
28
28
  | `mem_members` | `action` | `list` |
29
29
 
30
30
  `query` is required for recall; `task` never replaces it. `action` is required for
31
- wiki, commitments, spaces, grants, and members. `visibility` is `auto`,
32
- `private`, or `team` for recall, and `private` or `team` for remember, wiki, and
33
- forget; a space is chosen with `space`, never with `visibility`.
31
+ wiki, commitments, spaces, grants, and members. `visibility` is `auto` (the
32
+ default: the session's space, a bound shared space or else personal), `private`,
33
+ or `team` for recall and wiki, and `private` (the default) or `team` for remember
34
+ and forget; a space is chosen with `space`, never with `visibility`. wiki `write`
35
+ and `append` need `filename`, a flat name such as `project-harbour.md`.
34
36
 
35
37
  ```js
36
38
  mem_recall({ query: "migration ordering decision", task: "fix the migration ordering" })
@@ -104,6 +106,11 @@ Write in the same turn, without asking, when:
104
106
  | A promise, a reminder, or someone the person is waiting on | `mem_commitments` `action: "add"` |
105
107
  | Something known has changed | `mem_remember` with `supersedes: ["<old id>"]` |
106
108
 
109
+ `mem_remember` answers with the stored turn's id (`msg-…`); the memory's atom id
110
+ (`m_…`) appears after extraction, through `mem_recall`. `supersedes` takes atom
111
+ ids: the old atom is removed at once, and the new one is recallable after
112
+ extraction.
113
+
107
114
  Then say what you saved in one line. Check the session's recall results first:
108
115
  do not write a duplicate; supersede a conflict. One fact per call, with the date
109
116
  and source when known; write "assumed" when it is not verified.
@@ -142,12 +149,13 @@ keeps the private original. A revoke deletes the copy; it cannot undo a read.
142
149
 
143
150
  ## Forgetting
144
151
 
145
- When the person asks you to forget something, do it: the request is the
146
- confirmation. Ask first only for a delete you propose yourself, and for
147
- team-visible memory. Say what remains. `mem_forget` by id deletes atoms
152
+ One rule for every delete: the person's explicit request is their consent, so
153
+ do it without asking again; ask first when you propose the deletion yourself. The
154
+ host's own approval prompt is not a chat question. Say what remains. `mem_forget` by id deletes atoms
148
155
  and turns and lists other copies; `match` erases persona and scenario lines after
149
156
  a preview. A commitment is cancelled or deleted with `mem_commitments`. Page text
150
- is removed by editing the page. Supersede old facts; do not delete them for age.
157
+ is removed by editing the page; a page, a source file, or a whole wiki with
158
+ `mem_wiki` `delete`. Supersede old facts; do not delete them for age.
151
159
 
152
160
  ## Compaction
153
161
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@joe-broadhead/opencode-mem",
3
- "version": "0.8.2",
3
+ "version": "0.8.4",
4
4
  "type": "module",
5
5
  "description": "Durable private and shared-space memory for OpenCode agents",
6
6
  "license": "MIT",
@@ -89,7 +89,11 @@
89
89
  "input": {
90
90
  "type": "object",
91
91
  "additionalProperties": false,
92
- "properties": {}
92
+ "properties": {
93
+ "jellySpeaker": {
94
+ "type": "string"
95
+ }
96
+ }
93
97
  },
94
98
  "output": {
95
99
  "type": "object",
@@ -201,7 +205,11 @@
201
205
  "input": {
202
206
  "type": "object",
203
207
  "additionalProperties": false,
204
- "properties": {}
208
+ "properties": {
209
+ "jellySpeaker": {
210
+ "type": "string"
211
+ }
212
+ }
205
213
  },
206
214
  "output": {
207
215
  "type": "object",
@@ -263,6 +271,9 @@
263
271
  "minimum": 0,
264
272
  "maximum": 50,
265
273
  "multipleOf": 50
274
+ },
275
+ "jellySpeaker": {
276
+ "type": "string"
266
277
  }
267
278
  }
268
279
  },
@@ -348,7 +359,11 @@
348
359
  "input": {
349
360
  "type": "object",
350
361
  "additionalProperties": false,
351
- "properties": {}
362
+ "properties": {
363
+ "jellySpeaker": {
364
+ "type": "string"
365
+ }
366
+ }
352
367
  },
353
368
  "output": {
354
369
  "type": "object",
@@ -402,6 +417,9 @@
402
417
  "wiki": {
403
418
  "type": "string",
404
419
  "maxLength": 200
420
+ },
421
+ "jellySpeaker": {
422
+ "type": "string"
405
423
  }
406
424
  }
407
425
  },
@@ -457,6 +475,9 @@
457
475
  "ref": {
458
476
  "type": "string",
459
477
  "maxLength": 200
478
+ },
479
+ "jellySpeaker": {
480
+ "type": "string"
460
481
  }
461
482
  }
462
483
  },
@@ -498,6 +519,9 @@
498
519
  "open",
499
520
  "closed"
500
521
  ]
522
+ },
523
+ "jellySpeaker": {
524
+ "type": "string"
501
525
  }
502
526
  }
503
527
  },
@@ -668,7 +692,8 @@
668
692
  "memory.forget",
669
693
  "memory.promote",
670
694
  "memory.promote.revoke",
671
- "wiki.write"
695
+ "wiki.write",
696
+ "wiki.delete"
672
697
  ]
673
698
  },
674
699
  "files": [
@@ -29,9 +29,12 @@ Ten tools. In Code Mode (Jelly, or OpenCode with Code Mode on) call them inside
29
29
  - **`action` is required for wiki, commitments, spaces, grants, and members.**
30
30
  Calling them without it fails.
31
31
  - forget and promote have no `action`: their arguments choose what they do.
32
- - **`visibility` differs by tool.** Only recall takes `auto`; remember, wiki, and
33
- forget take `private` or `team`; there is no `space` visibility (a space is
34
- chosen with `space`).
32
+ - **`visibility` differs by tool.** recall and wiki take `auto` (the default: the
33
+ session's space, a bound shared space or else personal), `private`, or `team`;
34
+ remember and forget take `private` (the default) or `team`. There is no
35
+ `space` visibility (a space is chosen with `space`).
36
+ - **wiki `write` and `append` need `filename`**, a flat name such as
37
+ `project-harbour.md`.
35
38
  - **"Am I allowed to…?" starts with recall**, with the action in plain words.
36
39
  `spaces`, `grants`, and `members` say who can see what, not what the rules
37
40
  are.
@@ -41,7 +44,7 @@ Ten tools. In Code Mode (Jelly, or OpenCode with Code Mode on) call them inside
41
44
  | recall | `query` | none | `task`, `visibility` (`auto`, `private`, `team`), `limit`, `sources` (`memory`, `knowledge`, `all`), `type` (`persona`, `episodic`, `instruction`, `work_fact`, `work_method`, `work_artifact`), `knowledge_id`, `space` |
42
45
  | remember | `content` | none | `kind` (`preference`, `constraint`, `decision`, `fact`, `procedure`), `reason`, `supersedes`, `visibility` (`private`, `team`), `task`, `space` |
43
46
  | commitments | `action` | read-only: `list`; writes: `add`, `update`, `delete` | `what`, `owner`, `due`, `trigger`, `project`, `link`, `id`, `state` (`open`, `done`, `cancelled`, `all`), `due_before` |
44
- | wiki | `action` | read-only: `list`, `search`, `read`, `status`; writes: `create`, `write`, `append` | `query`, `wiki_id`, `ref`, `path`, `filename`, `name`, `content`, `ingest`, `knowledge_id`, `visibility` (`team`, `private`), `type` (`wiki`, `code-graph`, `all`), `space` |
47
+ | wiki | `action` | read-only: `list`, `search`, `read`, `status`; writes: `create`, `write`, `append`, `delete` | `query`, `wiki_id`, `ref`, `path`, `filename`, `name`, `content`, `ingest`, `confirm`, `knowledge_id`, `visibility` (`auto`, `private`, `team`), `type` (`wiki`, `code-graph`, `all`), `space` |
45
48
  | forget | `ids` or `match` | none | `layer` (`all`, `l0`, `l1`, `l2`, `l3`), `confirm`, `agent`, `visibility` (`private`, `team`), `task`, `space` |
46
49
  | promote | `ids` and `rationale`, or `revoke` | none | `name`, `space` |
47
50
  | status | none | none | `space` |
@@ -55,14 +58,14 @@ commitments: `add` needs `what`; `update` and `delete` need `id`; `list` takes
55
58
  ```js
56
59
  await tools.mem.recall({ query: "staging port", task: "fix the staging deploy" }) // mem_recall({ query: "staging port", task: "fix the staging deploy" })
57
60
  await tools.mem.remember({ content: "Summaries as a table, British spelling", kind: "preference", reason: "Stated by the person, 2026-11-05" }) // mem_remember({ content: "Summaries as a table, British spelling", kind: "preference", reason: "Stated by the person, 2026-11-05" })
58
- await tools.mem.remember({ content: "Staging listens on 8788 (verified 2026-11-05)", kind: "fact", supersedes: ["rec_..."] }) // mem_remember({ content: "Staging listens on 8788 (verified 2026-11-05)", kind: "fact", supersedes: ["rec_..."] })
61
+ await tools.mem.remember({ content: "Staging listens on 8788 (verified 2026-11-05)", kind: "fact", supersedes: ["m_..."] }) // mem_remember({ content: "Staging listens on 8788 (verified 2026-11-05)", kind: "fact", supersedes: ["m_..."] })
59
62
  await tools.mem.commitments({ action: "add", what: "Send the Q4 numbers to Ama", owner: "user", due: "2026-11-06" }) // mem_commitments({ action: "add", what: "Send the Q4 numbers to Ama", owner: "user", due: "2026-11-06" })
60
63
  await tools.mem.commitments({ action: "list" }) // mem_commitments({ action: "list" })
61
64
  await tools.mem.commitments({ action: "update", id: "cmt_...", state: "done" }) // mem_commitments({ action: "update", id: "cmt_...", state: "done" })
62
- await tools.mem.wiki({ action: "read", wiki_id: "wiki_...", filename: "projects/checkout-v3.md" }) // mem_wiki({ action: "read", wiki_id: "wiki_...", filename: "projects/checkout-v3.md" })
63
- await tools.mem.wiki({ action: "write", wiki_id: "wiki_...", filename: "projects/checkout-v3.md", content: "# Checkout v3" }) // mem_wiki({ action: "write", wiki_id: "wiki_...", filename: "projects/checkout-v3.md", content: "# Checkout v3" })
64
- await tools.mem.forget({ ids: ["rec_..."] }) // mem_forget({ ids: ["rec_..."] })
65
- await tools.mem.promote({ ids: ["rec_..."], rationale: "The team needs the logging rule", space: "space-team" }) // mem_promote({ ids: ["rec_..."], rationale: "The team needs the logging rule", space: "space-team" })
65
+ await tools.mem.wiki({ action: "read", wiki_id: "wiki_...", filename: "project-checkout-v3.md" }) // mem_wiki({ action: "read", wiki_id: "wiki_...", filename: "project-checkout-v3.md" })
66
+ await tools.mem.wiki({ action: "write", wiki_id: "wiki_...", filename: "project-checkout-v3.md", content: "# Checkout v3" }) // mem_wiki({ action: "write", wiki_id: "wiki_...", filename: "project-checkout-v3.md", content: "# Checkout v3" })
67
+ await tools.mem.forget({ ids: ["m_..."] }) // mem_forget({ ids: ["m_..."] })
68
+ await tools.mem.promote({ ids: ["m_..."], rationale: "The team needs the logging rule", space: "space-team" }) // mem_promote({ ids: ["m_..."], rationale: "The team needs the logging rule", space: "space-team" })
66
69
  await tools.mem.status({}) // mem_status({})
67
70
  await tools.mem.spaces({ action: "current" }) // mem_spaces({ action: "current" })
68
71
  await tools.mem.grants({ action: "list" }) // mem_grants({ action: "list" })
@@ -181,13 +184,19 @@ Put the why in `reason`. Include the date and source when known ("verified on
181
184
  **Supersede, do not stack.**
182
185
 
183
186
  ```js
184
- await tools.mem.recall({ query: "staging port" }) // shows rec_7f… "Staging listens on 8787"
185
- await tools.mem.remember({ content: "Staging listens on 8788 (changed 2026-11-05 with the proxy move)", kind: "fact", supersedes: ["rec_7f..."] })
187
+ await tools.mem.recall({ query: "staging port" }) // shows m_1730…_7f… "Staging listens on 8787"
188
+ await tools.mem.remember({ content: "Staging listens on 8788 (changed 2026-11-05 with the proxy move)", kind: "fact", supersedes: ["m_1730…_7f…"] })
186
189
  ```
187
190
 
188
- `supersedes` takes ids from your private memory. It removes those atoms once the
189
- new one is accepted, and says which it removed. Captured turns that mention the
190
- old value stay as history, with their dates.
191
+ `supersedes` takes atom ids (`m_…`, as recall shows them) from your private
192
+ memory; a turn id (`msg-…`) is refused. The old atoms are removed as soon as the
193
+ new memory is stored, and the answer says which. The new memory is recallable
194
+ only after extraction, so for a short while recall finds neither. Captured turns
195
+ that mention the old value stay as history, with their dates.
196
+
197
+ `remember` answers with the stored turn's id (`msg-…`). The memory's atom id
198
+ (`m_…`) appears once extraction runs, through `recall`; use that id to
199
+ supersede, share, or forget the atom later.
191
200
 
192
201
  **Trust the answer.** A write's answer says what is now stored, and an empty
193
202
  answer says what was checked. Do not read your own write back, and do not
@@ -281,31 +290,33 @@ the person approves (in Jelly: `jelly_routine_propose`, recurring only).
281
290
 
282
291
  ### The knowledge wiki
283
292
 
284
- Each space has one knowledge wiki: "My knowledge" in the personal space, "<space
285
- name> knowledge" in a shared one. Find it with `wiki` `list`; create it the first
286
- time a page is needed:
293
+ A space has no knowledge wiki until one is created. Keep one per space: "My
294
+ knowledge" in the personal space, "<space name> knowledge" in a shared one. Find
295
+ it with `wiki` `list`; create it the first time a page is needed (a write with no
296
+ wiki is refused, and the refusal shows this call):
287
297
 
288
298
  ```js
289
299
  await tools.mem.wiki({ action: "list" })
290
300
  await tools.mem.wiki({ action: "create", name: "My knowledge", visibility: "private", filename: "index.md", content: "# Index\n" })
291
301
  ```
292
302
 
293
- Its files:
303
+ Its files, all flat (the wiki cannot create folders yet, so a name such as
304
+ `projects/harbour.md` is refused before anything is asked):
294
305
 
295
306
  ```
296
307
  index.md - [Title](path): one line; updated YYYY-MM-DD
297
308
  log.md ## [YYYY-MM-DD] op | path | one line
298
- projects/<slug>.md
299
- people/<slug>.md private wiki only
300
- teams/<slug>.md
301
- decisions/<YYYY-MM-DD>-<slug>.md
302
- runbooks/<slug>.md
309
+ project-<slug>.md
310
+ person-<slug>.md private wiki only
311
+ team-<slug>.md
312
+ decision-<YYYY-MM-DD>-<slug>.md
313
+ runbook-<slug>.md
303
314
  glossary.md
304
315
  ```
305
316
 
306
317
  Slugs are lower-case and hyphenated, from the name people use. **Read `index.md`
307
318
  before creating a page**, and extend an existing page instead of creating a
308
- near-duplicate. Link pages with relative links, and cite atoms (`rec_…`), issues,
319
+ near-duplicate. Link pages with relative links, and cite atoms (`m_…`), issues,
309
320
  and PRs as evidence. A page never cites another page as proof.
310
321
 
311
322
  The "Memory records" wiki holds commitments. Do not read or write it with `wiki`;
@@ -325,14 +336,14 @@ One paragraph: what it is and why it exists.
325
336
  Two to five sentences. Replace the whole section on each update.
326
337
 
327
338
  ## Decisions
328
- - YYYY-MM-DD: <decision>, because <why>. (<rec_… / issue / PR>)
339
+ - YYYY-MM-DD: <decision>, because <why>. (<m_… / issue / PR>)
329
340
  - YYYY-MM-DD: ~~<old decision>~~ superseded on YYYY-MM-DD by the line above.
330
341
 
331
342
  ## Open questions
332
343
  - <question>
333
344
 
334
345
  ## People
335
- - [<Name>](../people/<slug>.md): <role in this project>
346
+ - [<Name>](person-<slug>.md): <role in this project>
336
347
 
337
348
  ## Links
338
349
  - <runbooks, decision pages, dashboards>
@@ -352,7 +363,7 @@ items. Checkboxes on a page become a second task board.
352
363
  - **Team**: purpose; what the team owns; conventions (each dated); how to reach
353
364
  them (a channel name, not an address); links. Do not copy the roster: point to
354
365
  `members`.
355
- - **Decision** (`decisions/<date>-<slug>.md`), only when the why does not fit in a
366
+ - **Decision** (`decision-<date>-<slug>.md`), only when the why does not fit in a
356
367
  sentence: Context; Decision; Alternatives considered; Consequences; Status
357
368
  (`accepted`, or `superseded by <link>` on a date).
358
369
  - **Runbook**: When to use; Steps; Checks; Rollback; "Last verified <date> by <who>".
@@ -371,21 +382,26 @@ items. Checkboxes on a page become a second task board.
371
382
  In Code Mode, do it in one `execute`:
372
383
 
373
384
  ```js
374
- const file = { wiki_id: "wiki_...", filename: "projects/checkout-v3.md" }
385
+ const file = { wiki_id: "wiki_...", filename: "project-checkout-v3.md" }
375
386
  const read = await tools.mem.wiki(Object.assign({ action: "read" }, file))
376
387
  let page = String(read?.content ?? read).replace(/^[\s\S]*?<knowledge[^>]*>\n/, "").replace(/\n<\/knowledge>\s*$/, "")
377
388
  page = page.replace(/## Status \(as of [^)]+\)\n[\s\S]*?(?=\n## )/, "## Status (as of 2026-11-05)\nLaunch moved to 18 Nov after the legal review; card storage is unchanged.\n")
378
389
  page = page.replace(/## Log\n/, "## Log\n- 2026-11-05: status updated after the launch review.\n")
379
- await tools.mem.wiki(Object.assign({ action: "write", content: page }, file))
380
- await tools.mem.wiki({ action: "append", wiki_id: "wiki_...", filename: "log.md", content: "## [2026-11-05] update | projects/checkout-v3.md | status after the launch review", ingest: false })
390
+ await tools.mem.wiki(Object.assign({ action: "write", content: page, ingest: false }, file))
391
+ await tools.mem.wiki({ action: "append", wiki_id: "wiki_...", filename: "log.md", content: "## [2026-11-05] update | project-checkout-v3.md | status after the launch review", ingest: true })
381
392
  ```
382
393
 
383
- Without Code Mode it is the same three calls. Ingestion is asynchronous, and
384
- `status` shows when pages are ready, but the source file you wrote can be read at
385
- once with `filename`.
394
+ Without Code Mode it is the same three calls. **Batch the writes:** every write
395
+ starts an ingest unless it passes `ingest: false`, and while a wiki ingests (a
396
+ few minutes) it refuses every write and delete. So pass `ingest: false` on each
397
+ write but the last, and `ingest: true` on the last one. A write to an ingesting
398
+ wiki is refused before anything is asked (`MEMORY_WIKI_BUSY`): wait until
399
+ `status` shows `ready`, then write again. The source file you wrote can be read
400
+ at once with `filename`; search finds it after ingestion.
386
401
 
387
- Each team wiki write asks the person, and the request shows the file and an
388
- excerpt. That is another reason to batch.
402
+ A wiki write to a shared space asks the person (the request shows the file and
403
+ an excerpt); a write to the personal space does not. By default `wiki` uses the
404
+ session's space, as `recall` does. That is another reason to batch.
389
405
 
390
406
  ## End of a piece of work
391
407
 
@@ -452,7 +468,7 @@ await tools.mem.remember({ content: "Production deploys need a signed changelog
452
468
  Sharing existing private memory, as a copy:
453
469
 
454
470
  ```js
455
- await tools.mem.promote({ ids: ["rec_..."], space: "space-team", name: "Release policy", rationale: "The platform team needs the agreed deploy rule" })
471
+ await tools.mem.promote({ ids: ["m_..."], space: "space-team", name: "Release policy", rationale: "The platform team needs the agreed deploy rule" })
456
472
  await tools.mem.promote({ revoke: "res_...", space: "space-team" }) // take it back
457
473
  ```
458
474
 
@@ -462,17 +478,20 @@ back what someone already read.
462
478
 
463
479
  ## Forgetting
464
480
 
465
- When the person asks you to forget something, forget it: the request is the
466
- confirmation, so do not ask again. Ask first only for a delete you propose
467
- yourself (a tidy-up, a duplicate) and for team-visible memory. Then say what
468
- remains.
481
+ One rule for every delete: **the person's explicit request is their consent**,
482
+ so when they ask you to forget or delete something, do it without asking again.
483
+ **Ask first when you propose the deletion yourself** (a tidy-up, a duplicate, a
484
+ copy that `forget` listed). The host's own approval prompt (for `forget`, for a
485
+ team delete, for a wiki delete) is not a chat question: do not repeat it in chat.
486
+ Then say what remains.
469
487
 
470
488
  | Forget | Call |
471
489
  |---|---|
472
- | An atom or a turn | `forget({ ids: ["rec_...", "msg_..."] })`; read the copies it lists, and delete them with the call it prints, after the person agrees |
490
+ | An atom or a turn | `forget({ ids: ["m_...", "msg-..."] })`; read the copies it lists, and delete them with the call it prints, after the person agrees |
473
491
  | A phrase in the persona or scenarios | `forget({ match: "staging port", layer: "all" })` previews; the same call with `confirm: true` applies |
474
492
  | A commitment | `commitments({ action: "update", id, state: "cancelled" })` when it was dropped; `commitments({ action: "delete", id })` when it must be gone |
475
493
  | Text on a page | Edit the page with `wiki` `write`; forget does not touch wikis |
494
+ | A page, a source file, or a whole wiki | `wiki({ action: "delete", wiki_id: "wiki_...", filename: "person-ama.md" })` previews; add `confirm: true` to delete (it always asks, then reads it back). `ref` deletes a generated page; `wiki_id` alone the whole wiki |
476
495
 
477
496
  `forget` is irreversible. It deletes each id only under the agent and session that
478
497
  wrote it; pass `agent` when another agent wrote them. It does not reach other
package/src/backend/v3.js CHANGED
@@ -33,7 +33,8 @@ export class BackendError extends Error {
33
33
  * a remembered fact, or a deletion, so these paths are deliberately absent:
34
34
  * the gateway's capture route, conversation/add,
35
35
  * conversation/delete, atomic/update, atomic/delete, scenario/write,
36
- * scenario/rm, core/write, wiki/delete, and meta/asset/touch-usage.
36
+ * scenario/rm, core/write, wiki/delete, wiki/raw/rm, wiki/page/rm, and
37
+ * meta/asset/touch-usage.
37
38
  */
38
39
  const RETRYABLE_READ_PATHS = new Set([
39
40
  "/v3/atomic/search",
@@ -541,15 +542,38 @@ export function createBackend(config, deps = {}) {
541
542
  },
542
543
 
543
544
  /**
544
- * Local mode only: revoking a share deletes its wiki directly. Through the
545
- * gateway this route is not on the data-plane allowlist; a revoke there
546
- * goes through `DELETE /v1/spaces/:id/resources/:resource_id`, which
547
- * checks the caller and reads the deletion back.
545
+ * Delete whole wikis. Local mode calls the hub directly. Through the
546
+ * gateway the plugin uses `DELETE /v1/spaces/:id/resources/:resource_id`
547
+ * instead (mem_promote revoke, mem_wiki delete), which checks the caller,
548
+ * deletes the content, reads it back, and removes the catalog row; the
549
+ * gateway answers this route with that same delete.
548
550
  */
549
551
  deleteWiki({ scope, wikiIDs }) {
550
552
  return knowledge("/v3/wiki/delete", { wiki_ids: wikiIDs }, scope)
551
553
  },
552
554
 
555
+ /**
556
+ * Delete source files. The hub also deletes the pages ingested only from
557
+ * them and rewrites the pages that cite them; it refuses while the wiki
558
+ * ingests (`409`). Never retried: a delete is not idempotent in its answer.
559
+ */
560
+ deleteWikiRaw({ scope, wikiID, filenames }) {
561
+ return knowledge(
562
+ "/v3/wiki/raw/rm",
563
+ { team_id: scope.team_id, wiki_id: wikiID, filenames, ...(scope.user_id ? { user_id: scope.user_id } : {}) },
564
+ scope,
565
+ )
566
+ },
567
+
568
+ /** Delete generated pages; the hub removes links to them from other pages. */
569
+ deleteWikiPages({ scope, wikiID, refs }) {
570
+ return knowledge(
571
+ "/v3/wiki/page/rm",
572
+ { team_id: scope.team_id, wiki_id: wikiID, refs, ...(scope.user_id ? { user_id: scope.user_id } : {}) },
573
+ scope,
574
+ )
575
+ },
576
+
553
577
  listAccessibleAssets({ scope, assetType }) {
554
578
  return core("/v3/meta/asset/list-accessible", { user_id: scope.user_id, asset_type: assetType, ...scope }, scope)
555
579
  },
@@ -21,9 +21,9 @@ export const PINNED_TOOLS = Object.freeze(["recall", "remember", "commitments",
21
21
  export const MEM_NAMESPACE_DESCRIPTION = [
22
22
  "Durable private and shared-space memory. Call as await tools.mem.<name>({...}); ? marks an optional key:",
23
23
  'recall({query, task?, visibility?: "auto"|"private"|"team", limit?}) — query is required, task never replaces it; "am I allowed" starts here;',
24
- 'remember({content, kind?, reason?, supersedes?, visibility?: "private"|"team"}) — supersedes takes the ids of atoms it replaces;',
24
+ 'remember({content, kind?, reason?, supersedes?, visibility?: "private"|"team"}) — supersedes takes the atom ids (m_…) it replaces; the answer gives the turn id (msg-…);',
25
25
  'commitments({action: "list"|"add"|"update"|"delete", what?, owner?, due?, id?, state?}) — add needs what (due is YYYY-MM-DD), update and delete need id;',
26
- 'wiki({action: "list"|"search"|"read"|"status"|"create"|"write"|"append", query?, wiki_id?, ref?, name?, content?});',
26
+ 'wiki({action: "list"|"search"|"read"|"status"|"create"|"write"|"append"|"delete", query?, wiki_id?, ref?, filename?, name?, content?, ingest?, confirm?}) — write and append need filename, a flat name such as "project-harbour.md"; delete previews unless confirm is true;',
27
27
  'spaces({action: "current"|"list"}); grants({action: "list", space?}); members({action: "list", space?});',
28
28
  "status({space?}); forget({ids} or {match, confirm?}) — visibility is private or team; promote({ids, rationale, space?} or {revoke, space?}).",
29
29
  "Search a tool by name for its other options.",