@joe-broadhead/opencode-mem 0.8.3 → 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,90 @@
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
+
6
90
  ## [0.8.3] - 2026-11-07
7
91
 
8
92
  Memory's views ask for the person who opened them (Jelly's resource-token
package/README.md CHANGED
@@ -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
@@ -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.3",
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",
@@ -692,7 +692,8 @@
692
692
  "memory.forget",
693
693
  "memory.promote",
694
694
  "memory.promote.revoke",
695
- "wiki.write"
695
+ "wiki.write",
696
+ "wiki.delete"
696
697
  ]
697
698
  },
698
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.",
package/src/curation.js CHANGED
@@ -35,6 +35,18 @@ const STATUS = [
35
35
  /\bon (?:the|my|our|a) to-?do list\b/i,
36
36
  /\btbd\b/i,
37
37
  /\bpending (?:confirmation|review|approval)\b/i,
38
+ // A status label opening a line: "Status: half done", "Progress - 3 of 5".
39
+ // Not "status 403", "Status codes:", or "Status-shaped writes".
40
+ /^\s*(?:status|progress)\s*(?::|[-–—]\s)/im,
41
+ // A line that opens as a work-in-progress marker: "WIP: auth", "In progress: x".
42
+ /^\s*(?:wip|in progress)\b\s*[:\-–—]?/im,
43
+ // Partly finished, said of something: "the walkthrough is half done". Not a
44
+ // rule about such things ("never ship half done migrations").
45
+ /\b(?:is|are|was|were|now|currently|still)\s+(?:about |roughly |around |only |just )?(?:half|mostly|nearly|almost|partly|partially)[- ](?:done|finished|complete|completed|through)\b/i,
46
+ // Progress as a share: "40% done", "70 % complete". Not "an error budget of 0.1%".
47
+ /\b\d{1,3}(?:\.\d+)?\s?%\s+(?:done|complete|completed|finished|through)\b/i,
48
+ // Under way, said of something: "the migration is under way".
49
+ /\b(?:is|are|was|were|now|currently|still)\s+(?:well\s+)?under\s?way\b/i,
38
50
  ]
39
51
 
40
52
  // The reply payload is a fixed all-caps token or a short quoted string that
@@ -1,7 +1,8 @@
1
1
  /**
2
2
  * The plugin's own default permission rules: `mem_forget` asks before it runs
3
- * (D17, "Forget asks"). Forgetting deletes, and a delete cannot be undone, so it
4
- * asks in every space; the other tools run as the agent's rules let them.
3
+ * (D17, "Forget asks"), and so does a wiki delete (`wiki.delete`, 0.8.4).
4
+ * Forgetting and deleting cannot be undone, so they ask in every space; the
5
+ * other tools run as the agent's rules let them.
5
6
  *
6
7
  * The engine consults a rule on a plugin tool's id only when the tool asserts
7
8
  * it, so `mem_forget` asserts `mem_forget` before it deletes
@@ -23,7 +24,12 @@
23
24
  /** @typedef {{ action: string, resource: string, effect: "allow" | "ask" | "deny" }} Rule */
24
25
 
25
26
  /** @type {readonly Rule[]} */
26
- export const DEFAULT_RULES = Object.freeze([Object.freeze({ action: "mem_forget", resource: "*", effect: "ask" })])
27
+ export const DEFAULT_RULES = Object.freeze([
28
+ Object.freeze({ action: "mem_forget", resource: "*", effect: "ask" }),
29
+ // A wiki delete always asks, private or team (mem_wiki delete with confirm),
30
+ // for the same reason: it cannot be undone. Jelly asks it through `asks`.
31
+ Object.freeze({ action: "wiki.delete", resource: "*", effect: "ask" }),
32
+ ])
27
33
 
28
34
  const BASE_ALLOW = { action: "*", resource: "*", effect: "allow" }
29
35
  const same = (a, b) => a?.action === b.action && a?.resource === b.resource && a?.effect === b.effect
@@ -53,6 +53,64 @@ export async function discoverKnowledge(backend, log, assetType, scope) {
53
53
 
54
54
  const DEFAULT_KNOWLEDGE_CHARS = 6000
55
55
  const DEFAULT_ASSET_CHARS = 3000
56
+ /** A hit's snippet, and how many linked pages a hit lists. */
57
+ const SNIPPET_CHARS = 160
58
+ const RELATED_PER_HIT = 5
59
+
60
+ /** A page path as read takes it: "wiki/entities/ama.md" -> "entities/ama". */
61
+ function pageRef(value) {
62
+ return String(value ?? "").replace(/^\/*wiki\//, "").replace(/\.md$/i, "")
63
+ }
64
+
65
+ /**
66
+ * A knowledge search answer as compact text. The hub's wiki search answers
67
+ * `{ results: [{ path, title, snippet, score, type, hop, related, via }],
68
+ * links, count }`, and printing that JSON spent tokens on scores, types and
69
+ * hop counts. Each hit is one line, its path (what read takes as ref), its
70
+ * title when it says more than the path, and a short snippet; the pages it
71
+ * links to follow on one line as refs. A code graph's `{ text }` is its text.
72
+ * Anything else is one line of JSON.
73
+ *
74
+ * @param {unknown} result
75
+ * @returns {string}
76
+ */
77
+ export function renderSearchHits(result) {
78
+ if (typeof result === "string") return result
79
+ if (result && typeof result === "object" && !Array.isArray(result) && typeof result.text === "string") return result.text
80
+ const hits = Array.isArray(result?.results) ? result.results : Array.isArray(result) ? result : null
81
+ if (!hits) return JSON.stringify(result ?? null)
82
+ if (hits.length === 0) return "no matching pages"
83
+ const lines = []
84
+ for (const hit of hits) {
85
+ if (!hit || typeof hit !== "object") {
86
+ lines.push(`- ${oneLine(String(hit), SNIPPET_CHARS)}`)
87
+ continue
88
+ }
89
+ const path = oneLine(hit.path ?? hit.id ?? hit.ref ?? "", 160)
90
+ const title = oneLine(hit.title ?? "", 100)
91
+ const named = title && title.toLowerCase() !== pageRef(path).split("/").at(-1)?.toLowerCase() ? ` | ${title}` : ""
92
+ const linked = Number(hit.hop) > 0 ? " (via a link)" : ""
93
+ const snippet = oneLine(String(hit.snippet ?? hit.content ?? "").replace(/\s+/g, " "), SNIPPET_CHARS)
94
+ lines.push(`- ${path}${named}${linked}${snippet ? `: ${snippet}` : ""}`)
95
+ const related = (Array.isArray(hit.related) ? hit.related : [])
96
+ .map((entry) => (typeof entry === "string" ? pageRef(entry) : pageRef(entry?.path ?? entry?.title ?? "")))
97
+ .filter(Boolean)
98
+ if (related.length > 0) {
99
+ const more = related.length > RELATED_PER_HIT ? `, +${related.length - RELATED_PER_HIT}` : ""
100
+ lines.push(` → ${related.slice(0, RELATED_PER_HIT).map((ref) => oneLine(ref, 80)).join(", ")}${more}`)
101
+ }
102
+ }
103
+ return lines.join("\n")
104
+ }
105
+
106
+ /** Cut text to `max` characters at a line end, and count the hits left out. */
107
+ function clipLines(value, max) {
108
+ if (value.length <= max) return value
109
+ const cut = value.lastIndexOf("\n", max - 40)
110
+ const kept = cut > 0 ? value.slice(0, cut) : value.slice(0, Math.max(0, max - 40))
111
+ const omitted = (value.slice(kept.length).match(/^- /gm) ?? []).length
112
+ return `${kept}\n(+${omitted || "more"} hit(s) not shown)`
113
+ }
56
114
 
57
115
  /**
58
116
  * Search knowledge assets and render the results as fenced data.
@@ -85,14 +143,14 @@ export async function searchKnowledge(backend, ids, query, scoped, options = {})
85
143
  params: { query, limit: 5 },
86
144
  scope: scoped,
87
145
  })
88
- const rendered = typeof result === "string" ? result : JSON.stringify(result, null, 2)
146
+ const rendered = renderSearchHits(result)
89
147
  // A planted command in a page is data: it is removed, marked, and noted
90
148
  // outside the fence, as recall does for atoms.
91
149
  const safe = quarantineText(rendered)
92
150
  const note = quarantineNote(safe.removed)
93
151
  // Truncate first, then neutralize: the closing tag is appended after,
94
152
  // so neither a long page nor a crafted one can escape the fence.
95
- const body = neutralizeFenceClosers(safe.text.slice(0, bodyRoom))
153
+ const body = neutralizeFenceClosers(clipLines(safe.text, bodyRoom).slice(0, bodyRoom))
96
154
  const block = `<knowledge source="${source}">\n${body}\n</knowledge>${note ? `\n${note}` : ""}`
97
155
  blocks.push(block)
98
156
  used += block.length + 2