@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 +84 -0
- package/README.md +4 -2
- package/docs/agent-protocol.md +16 -8
- package/package.json +3 -2
- package/skills/mem.usage/SKILL.md +60 -41
- package/src/backend/v3.js +29 -5
- package/src/call-shapes.js +2 -2
- package/src/curation.js +12 -0
- package/src/permissions.js +9 -3
- package/src/tools/knowledge.js +60 -2
- package/src/tools/memory.js +40 -12
- package/src/tools/wiki.js +484 -82
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.
|
|
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
|
|
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
|
package/docs/agent-protocol.md
CHANGED
|
@@ -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
|
-
|
|
33
|
-
|
|
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
|
-
|
|
146
|
-
|
|
147
|
-
|
|
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
|
|
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
|
+
"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.**
|
|
33
|
-
|
|
34
|
-
|
|
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` (`
|
|
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: ["
|
|
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: "
|
|
63
|
-
await tools.mem.wiki({ action: "write", wiki_id: "wiki_...", filename: "
|
|
64
|
-
await tools.mem.forget({ ids: ["
|
|
65
|
-
await tools.mem.promote({ ids: ["
|
|
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
|
|
185
|
-
await tools.mem.remember({ content: "Staging listens on 8788 (changed 2026-11-05 with the proxy move)", kind: "fact", supersedes: ["
|
|
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
|
|
189
|
-
|
|
190
|
-
|
|
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
|
-
|
|
285
|
-
name> knowledge" in a shared one. Find
|
|
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
|
-
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
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 (`
|
|
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>. (<
|
|
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>](
|
|
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** (`
|
|
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: "
|
|
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 |
|
|
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.
|
|
384
|
-
|
|
385
|
-
|
|
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
|
-
|
|
388
|
-
excerpt
|
|
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: ["
|
|
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
|
-
|
|
466
|
-
|
|
467
|
-
yourself (a tidy-up, a duplicate
|
|
468
|
-
|
|
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: ["
|
|
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,
|
|
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
|
-
*
|
|
545
|
-
* gateway
|
|
546
|
-
*
|
|
547
|
-
*
|
|
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
|
},
|
package/src/call-shapes.js
CHANGED
|
@@ -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
|
|
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
|
package/src/permissions.js
CHANGED
|
@@ -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")
|
|
4
|
-
*
|
|
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([
|
|
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
|
package/src/tools/knowledge.js
CHANGED
|
@@ -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 =
|
|
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
|