@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 +136 -0
- package/README.md +31 -5
- package/docs/agent-protocol.md +16 -8
- package/package.json +30 -5
- package/skills/mem.usage/SKILL.md +60 -41
- package/src/backend/v3.js +29 -5
- package/src/call-shapes.js +2 -2
- package/src/credentials.js +103 -19
- 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/src/views/contracts.js +36 -26
- package/src/views/rpc.js +78 -17
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
|
|
197
|
-
`token("memory")` as before, which Jelly answers
|
|
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.
|
|
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
|
|
@@ -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
|
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",
|
|
@@ -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.**
|
|
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.",
|