@joe-broadhead/opencode-mem 0.9.2 → 0.9.12

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.
Files changed (64) hide show
  1. package/CHANGELOG.md +1605 -0
  2. package/README.md +135 -43
  3. package/docs/agent-protocol.md +29 -28
  4. package/docs/permissions.md +148 -0
  5. package/package.json +277 -16
  6. package/skills/mem.pages/SKILL.md +35 -16
  7. package/skills/mem.sharing/SKILL.md +39 -6
  8. package/skills/mem.sources/SKILL.md +41 -10
  9. package/skills/mem.usage/SKILL.md +47 -16
  10. package/src/backend/records.js +413 -50
  11. package/src/backend/v3.js +15 -10
  12. package/src/call-shapes.js +18 -25
  13. package/src/capture-pause.js +136 -0
  14. package/src/capture.js +7 -4
  15. package/src/collector-service.js +212 -35
  16. package/src/collector.js +186 -47
  17. package/src/commands.js +37 -0
  18. package/src/compaction.js +4 -2
  19. package/src/config.js +162 -1
  20. package/src/connect.js +353 -0
  21. package/src/copies.js +28 -3
  22. package/src/credentials.js +35 -7
  23. package/src/curation.js +33 -14
  24. package/src/events.js +144 -36
  25. package/src/forget-purge.js +377 -0
  26. package/src/forgotten.js +356 -0
  27. package/src/hooks.js +9 -4
  28. package/src/index.js +25 -6
  29. package/src/permissions.js +116 -38
  30. package/src/protocol.js +21 -11
  31. package/src/records.js +4 -1
  32. package/src/runtime.js +207 -16
  33. package/src/shapes.js +63 -0
  34. package/src/sources.js +183 -12
  35. package/src/spaces.js +58 -1
  36. package/src/spool.js +442 -64
  37. package/src/stated.js +334 -0
  38. package/src/storable.js +477 -0
  39. package/src/tools/aliases.js +36 -147
  40. package/src/tools/commitments.js +69 -12
  41. package/src/tools/held-write.js +9 -1
  42. package/src/tools/index.js +29 -44
  43. package/src/tools/ingest.js +33 -128
  44. package/src/tools/memory.js +594 -901
  45. package/src/tools/page-sections.js +147 -0
  46. package/src/tools/page.js +314 -82
  47. package/src/tools/recall-browse.js +173 -0
  48. package/src/tools/recall.js +79 -19
  49. package/src/tools/share.js +494 -131
  50. package/src/tools/shared.js +97 -19
  51. package/src/tools/spaces.js +215 -104
  52. package/src/tools/status.js +31 -3
  53. package/src/tools/wiki.js +5 -13
  54. package/src/util.js +10 -20
  55. package/src/views/contracts.js +137 -6
  56. package/src/views/overdue.js +125 -0
  57. package/src/views/profile.js +154 -0
  58. package/src/views/records-reads.js +132 -33
  59. package/src/views/rpc.js +63 -12
  60. package/src/views/shape.js +49 -0
  61. package/views/commitments.html +31 -4
  62. package/views/home.html +22 -3
  63. package/views/memory.html +126 -24
  64. package/src/erase.js +0 -36
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@joe-broadhead/opencode-mem",
3
- "version": "0.9.2",
3
+ "version": "0.9.12",
4
4
  "type": "module",
5
5
  "description": "Durable private and shared-space memory for OpenCode agents",
6
6
  "license": "MIT",
@@ -85,14 +85,14 @@
85
85
  {
86
86
  "name": "mem.forget",
87
87
  "permission": "mem_forget",
88
- "effect": "ask",
89
- "readOnly": false
88
+ "effect": "allow",
89
+ "readOnly": true
90
90
  },
91
91
  {
92
92
  "name": "mem.promote",
93
93
  "permission": "mem_promote",
94
94
  "effect": "allow",
95
- "readOnly": false
95
+ "readOnly": true
96
96
  },
97
97
  {
98
98
  "name": "mem.status",
@@ -151,12 +151,21 @@
151
151
  "type": "string",
152
152
  "maxLength": 400
153
153
  },
154
+ "state": {
155
+ "type": "string",
156
+ "enum": [
157
+ "unconfigured",
158
+ "refused",
159
+ "unreachable"
160
+ ]
161
+ },
154
162
  "credential": {
155
163
  "type": "string",
156
164
  "enum": [
157
165
  "jelly",
158
166
  "key",
159
167
  "option",
168
+ "opencode",
160
169
  "none"
161
170
  ]
162
171
  },
@@ -330,6 +339,10 @@
330
339
  "maximum": 50,
331
340
  "multipleOf": 50
332
341
  },
342
+ "space": {
343
+ "type": "string",
344
+ "maxLength": 200
345
+ },
333
346
  "jellySpeaker": {
334
347
  "type": "string"
335
348
  }
@@ -340,6 +353,8 @@
340
353
  "additionalProperties": false,
341
354
  "required": [
342
355
  "space",
356
+ "spaces",
357
+ "incomplete",
343
358
  "items",
344
359
  "more"
345
360
  ],
@@ -371,6 +386,64 @@
371
386
  }
372
387
  }
373
388
  },
389
+ "spaces": {
390
+ "type": "array",
391
+ "maxItems": 100,
392
+ "items": {
393
+ "type": "object",
394
+ "additionalProperties": false,
395
+ "required": [
396
+ "id",
397
+ "name",
398
+ "kind"
399
+ ],
400
+ "properties": {
401
+ "id": {
402
+ "type": "string",
403
+ "maxLength": 200
404
+ },
405
+ "name": {
406
+ "type": "string",
407
+ "maxLength": 200
408
+ },
409
+ "kind": {
410
+ "type": "string",
411
+ "enum": [
412
+ "personal",
413
+ "shared",
414
+ "unknown"
415
+ ]
416
+ }
417
+ }
418
+ }
419
+ },
420
+ "incomplete": {
421
+ "type": "array",
422
+ "maxItems": 100,
423
+ "items": {
424
+ "type": "object",
425
+ "additionalProperties": false,
426
+ "required": [
427
+ "id",
428
+ "name",
429
+ "reason"
430
+ ],
431
+ "properties": {
432
+ "id": {
433
+ "type": "string",
434
+ "maxLength": 200
435
+ },
436
+ "name": {
437
+ "type": "string",
438
+ "maxLength": 200
439
+ },
440
+ "reason": {
441
+ "type": "string",
442
+ "maxLength": 200
443
+ }
444
+ }
445
+ }
446
+ },
374
447
  "items": {
375
448
  "type": "array",
376
449
  "maxItems": 50,
@@ -381,7 +454,9 @@
381
454
  "id",
382
455
  "text",
383
456
  "type",
384
- "at"
457
+ "at",
458
+ "space",
459
+ "status"
385
460
  ],
386
461
  "properties": {
387
462
  "id": {
@@ -399,6 +474,41 @@
399
474
  "at": {
400
475
  "type": "string",
401
476
  "maxLength": 40
477
+ },
478
+ "space": {
479
+ "type": "object",
480
+ "additionalProperties": false,
481
+ "required": [
482
+ "id",
483
+ "name"
484
+ ],
485
+ "properties": {
486
+ "id": {
487
+ "type": "string",
488
+ "maxLength": 200
489
+ },
490
+ "name": {
491
+ "type": "string",
492
+ "maxLength": 200
493
+ }
494
+ }
495
+ },
496
+ "status": {
497
+ "type": "string",
498
+ "maxLength": 20
499
+ },
500
+ "stated_by": {
501
+ "type": "string",
502
+ "enum": [
503
+ "person",
504
+ "agent",
505
+ "inferred",
506
+ "external"
507
+ ]
508
+ },
509
+ "source": {
510
+ "type": "string",
511
+ "maxLength": 200
402
512
  }
403
513
  }
404
514
  }
@@ -1038,6 +1148,7 @@
1038
1148
  "additionalProperties": false,
1039
1149
  "required": [
1040
1150
  "id",
1151
+ "status",
1041
1152
  "action",
1042
1153
  "title",
1043
1154
  "target",
@@ -1054,6 +1165,10 @@
1054
1165
  "type": "string",
1055
1166
  "maxLength": 200
1056
1167
  },
1168
+ "status": {
1169
+ "type": "string",
1170
+ "maxLength": 20
1171
+ },
1057
1172
  "action": {
1058
1173
  "type": "string",
1059
1174
  "maxLength": 40
@@ -1080,6 +1195,10 @@
1080
1195
  "unknown"
1081
1196
  ]
1082
1197
  },
1198
+ "source": {
1199
+ "type": "string",
1200
+ "maxLength": 200
1201
+ },
1083
1202
  "external": {
1084
1203
  "type": "boolean"
1085
1204
  },
@@ -1158,7 +1277,7 @@
1158
1277
  "properties": {
1159
1278
  "items": {
1160
1279
  "type": "array",
1161
- "maxItems": 20,
1280
+ "maxItems": 64,
1162
1281
  "items": {
1163
1282
  "type": "object",
1164
1283
  "additionalProperties": false,
@@ -1178,7 +1297,8 @@
1178
1297
  "category": {
1179
1298
  "type": "string",
1180
1299
  "enum": [
1181
- "request"
1300
+ "request",
1301
+ "commitment"
1182
1302
  ]
1183
1303
  },
1184
1304
  "label": {
@@ -1827,6 +1947,134 @@
1827
1947
  }
1828
1948
  }
1829
1949
  }
1950
+ },
1951
+ {
1952
+ "name": "profile.read",
1953
+ "label": "read what Memory holds about you",
1954
+ "permission": "mem_recall",
1955
+ "readOnly": true,
1956
+ "input": {
1957
+ "type": "object",
1958
+ "additionalProperties": false,
1959
+ "properties": {
1960
+ "jellySpeaker": {
1961
+ "type": "string"
1962
+ }
1963
+ }
1964
+ },
1965
+ "output": {
1966
+ "type": "object",
1967
+ "additionalProperties": false,
1968
+ "required": [
1969
+ "space",
1970
+ "label",
1971
+ "items",
1972
+ "more",
1973
+ "incomplete",
1974
+ "notes"
1975
+ ],
1976
+ "properties": {
1977
+ "space": {
1978
+ "type": "object",
1979
+ "additionalProperties": false,
1980
+ "required": [
1981
+ "id",
1982
+ "name",
1983
+ "kind"
1984
+ ],
1985
+ "properties": {
1986
+ "id": {
1987
+ "type": "string",
1988
+ "maxLength": 200
1989
+ },
1990
+ "name": {
1991
+ "type": "string",
1992
+ "maxLength": 200
1993
+ },
1994
+ "kind": {
1995
+ "type": "string",
1996
+ "enum": [
1997
+ "personal",
1998
+ "shared",
1999
+ "unknown"
2000
+ ]
2001
+ }
2002
+ }
2003
+ },
2004
+ "label": {
2005
+ "type": "string",
2006
+ "maxLength": 300
2007
+ },
2008
+ "items": {
2009
+ "type": "array",
2010
+ "maxItems": 24,
2011
+ "items": {
2012
+ "type": "object",
2013
+ "additionalProperties": false,
2014
+ "required": [
2015
+ "id",
2016
+ "layer",
2017
+ "agent",
2018
+ "path",
2019
+ "summary",
2020
+ "text",
2021
+ "clipped",
2022
+ "updated"
2023
+ ],
2024
+ "properties": {
2025
+ "id": {
2026
+ "type": "string",
2027
+ "maxLength": 200
2028
+ },
2029
+ "layer": {
2030
+ "type": "string",
2031
+ "enum": [
2032
+ "persona",
2033
+ "scenario"
2034
+ ]
2035
+ },
2036
+ "agent": {
2037
+ "type": "string",
2038
+ "maxLength": 80
2039
+ },
2040
+ "path": {
2041
+ "type": "string",
2042
+ "maxLength": 200
2043
+ },
2044
+ "summary": {
2045
+ "type": "string",
2046
+ "maxLength": 300
2047
+ },
2048
+ "text": {
2049
+ "type": "string",
2050
+ "maxLength": 12000
2051
+ },
2052
+ "clipped": {
2053
+ "type": "boolean"
2054
+ },
2055
+ "updated": {
2056
+ "type": "string",
2057
+ "maxLength": 40
2058
+ }
2059
+ }
2060
+ }
2061
+ },
2062
+ "more": {
2063
+ "type": "boolean"
2064
+ },
2065
+ "incomplete": {
2066
+ "type": "boolean"
2067
+ },
2068
+ "notes": {
2069
+ "type": "array",
2070
+ "maxItems": 8,
2071
+ "items": {
2072
+ "type": "string",
2073
+ "maxLength": 200
2074
+ }
2075
+ }
2076
+ }
2077
+ }
1830
2078
  }
1831
2079
  ],
1832
2080
  "views": [
@@ -1879,7 +2127,8 @@
1879
2127
  "wiki.list",
1880
2128
  "wiki.pages",
1881
2129
  "wiki.read",
1882
- "commitments.list"
2130
+ "commitments.list",
2131
+ "profile.read"
1883
2132
  ]
1884
2133
  },
1885
2134
  {
@@ -1998,6 +2247,12 @@
1998
2247
  "type": "boolean",
1999
2248
  "description": "On by default: finished turns are saved to your private memory. Off: the memory tools still work, and nothing is saved unless the agent is asked to remember it."
2000
2249
  },
2250
+ {
2251
+ "key": "skipAsks",
2252
+ "label": "Run without asking",
2253
+ "type": "string",
2254
+ "description": "Empty by default. Memory's asks to turn off, separated by commas, such as memory.forget, page.delete; a deny still stands. The full list is in Memory's docs/permissions.md. A team write held in your Inbox still waits there."
2255
+ },
2001
2256
  {
2002
2257
  "key": "token",
2003
2258
  "label": "Memory key",
@@ -2010,10 +2265,8 @@
2010
2265
  "memory"
2011
2266
  ],
2012
2267
  "asks": [
2013
- "memory.remember",
2014
2268
  "memory.forget",
2015
2269
  "memory.promote",
2016
- "memory.promote.revoke",
2017
2270
  "wiki.write",
2018
2271
  "wiki.delete",
2019
2272
  "memory.revise",
@@ -2022,7 +2275,9 @@
2022
2275
  "share.grant",
2023
2276
  "share.revoke",
2024
2277
  "share.transfer",
2025
- "sources.bind"
2278
+ "share.move",
2279
+ "session.bind",
2280
+ "sources.unbind"
2026
2281
  ],
2027
2282
  "routines": [
2028
2283
  {
@@ -2053,6 +2308,7 @@
2053
2308
  "views/pages.html",
2054
2309
  "views/graph.html",
2055
2310
  "docs/agent-protocol.md",
2311
+ "docs/permissions.md",
2056
2312
  "!docs/README.md",
2057
2313
  "README.md",
2058
2314
  "LICENSE",
@@ -2064,12 +2320,12 @@
2064
2320
  "access": "public"
2065
2321
  },
2066
2322
  "scripts": {
2067
- "test": "node --experimental-strip-types --test test/*.test.js",
2068
- "test:load": "node --test test/load-harness.test.js test/load-gateway.test.js",
2069
- "test:ops": "node --test test/ops-control.test.js",
2070
- "test:eval": "node --test test/agent-eval.test.js",
2323
+ "test": "node --experimental-strip-types --import ./test/support/tmp-isolation.js --test test/*.test.js",
2324
+ "test:load": "node --import ./test/support/tmp-isolation.js --test test/load-harness.test.js test/load-gateway.test.js",
2325
+ "test:ops": "node --import ./test/support/tmp-isolation.js --test test/ops-control.test.js",
2326
+ "test:eval": "node --import ./test/support/tmp-isolation.js --test test/agent-eval.test.js",
2071
2327
  "test:pack": "node --test test/package-contents.test.js",
2072
- "test:records": "node --disable-warning=ExperimentalWarning --test records/test/*.test.js",
2328
+ "test:records": "node --disable-warning=ExperimentalWarning --import ./test/support/tmp-isolation.js --test records/test/*.test.js",
2073
2329
  "eval:agent": "node scripts/eval/agent-eval.mjs",
2074
2330
  "eval:core": "node scripts/eval/agent-eval.mjs --suite core --runs 1 --timeout 120",
2075
2331
  "eval:core:release": "node scripts/eval/agent-eval.mjs --suite core --runs 3 --timeout 120",
@@ -2082,6 +2338,11 @@
2082
2338
  "eval:closed-book": "node scripts/eval/agent-eval.mjs --suite core --closed-book --runs 1 --timeout 120 --scenario core-recall-model --scenario core-recall-orb --scenario core-recall-port --scenario core-recall-region --scenario core-prior-db --scenario core-prior-version --scenario core-source-attribution --scenario core-preference --scenario core-update-owner --scenario core-update-region",
2083
2339
  "eval:agent:list": "node scripts/eval/agent-eval.mjs --list",
2084
2340
  "eval:controls": "node scripts/eval/controls.mjs",
2341
+ "eval:regrade": "node scripts/eval/regrade.mjs",
2342
+ "eval:c1": "node scripts/eval/c1.mjs",
2343
+ "eval:gate-v2": "node scripts/eval/gate-v2.mjs",
2344
+ "eval:writes": "node scripts/eval/write-allowlist.mjs",
2345
+ "eval:asks": "node scripts/eval/ask-policy.mjs",
2085
2346
  "load:spaces": "node scripts/loadtest-spaces.mjs",
2086
2347
  "load:gateway": "node scripts/loadtest-gateway.mjs",
2087
2348
  "load:cell": "node scripts/loadtest-cell.mjs",
@@ -26,28 +26,45 @@ await tools.mem.page({ action: "list", prefix: "projects/" }) // mem_page({ ac
26
26
  await tools.mem.page({ action: "read", path: "people/ama" }) // mem_page({ action: "read", path: "people/ama" })
27
27
  ```
28
28
 
29
- `read` shows the fields, the body, what the page links to and what links to it
30
- (backlinks), with its version. Before creating a page at an unknown path, check
31
- for an existing one rather than making a near-duplicate.
29
+ `read` shows the metadata first (fields, sections, links, backlinks, version),
30
+ then the body alone inside `<page_body>`. Only the text inside it is the page:
31
+ never copy the metadata or the markers into a write, which refuses them. Before
32
+ creating a page at an unknown path, check for an existing one rather than
33
+ making a near-duplicate.
32
34
 
33
- ## Write and append
35
+ ## Replace, append and write
34
36
 
35
37
  ```js
36
- await tools.mem.page({ action: "append", path: "projects/checkout-v3", section: "Log", content: "2026-11-05: launch moved to 18 Nov after the legal review." })
37
- await tools.mem.page({ action: "write", path: "projects/checkout-v3", title: "Checkout v3", content: "# Checkout v3\n\n## Status (as of 2026-11-05)\nLaunch moved to 18 Nov after the legal review.\n" })
38
+ await tools.mem.page({ action: "replace", path: "projects/checkout-v3", section: "Status", content: "- Launch 18 Nov, after the legal review (2026-11-05)." })
39
+ await tools.mem.page({ action: "append", path: "projects/checkout-v3", section: "Log", content: "- 2026-11-05: launch moved to 18 Nov after the legal review." })
38
40
  ```
39
41
 
42
+ - `replace` sets one `## section`'s text and keeps every other line: Status,
43
+ Purpose, People. "Status" also finds "Status (as of …)", for append too. A
44
+ name that fits two headings is refused, with their lines: rename or merge
45
+ one with `write`. Close any code fence you open. If someone changed that
46
+ section since this session's read, it is a conflict: read, merge, replace again.
40
47
  - `append` adds one line under a `## section`, creating it when missing: Log,
41
- Timeline, Decisions. Append once per change; don't re-read a successful write
42
- unless the answer depends on the updated page.
43
- - `write` replaces the whole body. Read an existing page before writing; merge
44
- your changes and write again. A missing or stale version conflicts; read the
45
- latest page and merge again rather than overwriting it.
46
- - One write per page per session, at a phase boundary. **Replace** Status,
47
- Purpose and People; **append** to Log and Timeline. Date every "now" claim.
48
+ Timeline, Decisions. On the person's own pages, one Log line per change,
49
+ starting with "- ". Don't re-read a successful write unless the answer
50
+ depends on the updated page.
51
+ - `write` replaces the whole body: for a new page or a restructure. Read the
52
+ page first, send only the body; a missing or stale version conflicts, so
53
+ read the latest and merge rather than overwrite.
54
+ - Date every "now" claim.
48
55
  - A shared write follows host permission settings: it defaults to ask, but an
49
56
  allow or remembered always may proceed without a prompt. Jelly with
50
- `heldTeamWrites` holds it in the Inbox. A private write never asks.
57
+ `heldTeamWrites` holds it in the Inbox. A private write never asks
58
+ (docs/permissions.md says how to change any ask).
59
+ - Where a page lands: `journal/` always in the personal space; a page that
60
+ exists in the session's shared space stays there; a new page is personal
61
+ unless the call passes the shared `space`, only when the person asked.
62
+ - On a team page (one that exists in a shared space) an agent only adds
63
+ lines, and only what the person asked for: `append` it, such as a dated
64
+ "Status:" line. No Log line, timeline entry or "noted that…" about your own
65
+ change; that bookkeeping is for the person's own pages. `write`,
66
+ `replace`, `move` and `delete` are refused there, and a journal page is
67
+ never written there. The person edits or removes lines in Memory's console.
51
68
 
52
69
  ## Links and timelines
53
70
 
@@ -63,7 +80,8 @@ await tools.mem.page({ action: "move", path: "topics/pricing", to: "projects/pri
63
80
 
64
81
  A **Timeline** section is a dated list of what happened with a person or a
65
82
  project. The daily routine appends to it, each line citing its source; append to
66
- it yourself with the date first.
83
+ it yourself with the date first, on the person's own pages (a team page gets
84
+ only what the person asked for).
67
85
 
68
86
  ## Page templates
69
87
 
@@ -112,7 +130,8 @@ with `revise`.
112
130
  ## The dashboard
113
131
 
114
132
  `index` is the dashboard, pinned at the start of every session (at most 60
115
- lines). The routine owns only the block between `<!-- routine:dashboard -->` and
133
+ lines). Writing, appending to or moving it asks the person, in every space:
134
+ it changes what every later session starts with. The routine owns only the block between `<!-- routine:dashboard -->` and
116
135
  `<!-- /routine -->` (goals, active projects, due items, recent decisions, what
117
136
  needs review) and keeps everything the person writes outside it. To set goals,
118
137
  write them above the block:
@@ -27,13 +27,38 @@ await tools.mem.share({ action: "grant", path: "projects/checkout-v3", to: "ama@
27
27
  await tools.mem.share({ action: "grant", path: "projects/", to: "group:grp_...", role: "viewer", expires: "2026-12-31" })
28
28
  await tools.mem.share({ action: "copy", ids: ["rec_..."], rationale: "The platform team needs the agreed deploy rule", space: "space-team" })
29
29
  await tools.mem.share({ action: "list" }) // what is shared, and with whom
30
+ await tools.mem.share({ action: "list", to: "me" }) // what others shared with you, in every space
31
+ ```
32
+
33
+ An email finds anyone in your organisation who has signed in to Memory, in a
34
+ space with you or not: two people with only their personal spaces can share
35
+ pages. Pass the exact address. When no one has it, the answer says to ask them
36
+ to sign in once at the Memory server's `/login`, then share again.
37
+
38
+ `list` with `"to": "me"` gives each page or folder shared with you, with who
39
+ owns it, the role, the end date and the `mem_page` call that reads it, with
40
+ its `space`. Use that call: such a space is not yours, and its other pages
41
+ stay hidden.
42
+
43
+ ## Moving between spaces
44
+
45
+ `move` moves memories or commitments (`ids`) or a page or folder (`path`) from
46
+ `space` to the space in `to`, either way: shared to `"personal"` too. Each copy is
47
+ read back before its original is deleted, and names its source. A move is not a forget: nothing is fingerprinted, so recall in
48
+ the new space finds them. It asks once for the batch; `keep: true`
49
+ copies instead. Moving a page out needs admin; someone else's memory, too.
50
+
51
+ ```js
52
+ await tools.mem.share({ action: "move", ids: ["rec_..."], space: "space-team", to: "personal" })
53
+ await tools.mem.share({ action: "move", path: "projects/old/", space: "space-team", to: "personal" })
30
54
  ```
31
55
 
32
56
  ## Taking it back, handing it over
33
57
 
34
58
  ```js
35
59
  await tools.mem.share({ action: "revoke", grant_id: "grt_..." }) // one grant
36
- await tools.mem.share({ action: "revoke", path: "projects/checkout-v3" }) // stop sharing the page with everyone
60
+ await tools.mem.share({ action: "revoke", path: "projects/checkout-v3", to: "sam@example.com" }) // only Sam's grants
61
+ await tools.mem.share({ action: "revoke", path: "projects/checkout-v3", to: "everyone" }) // only when the person says everyone
37
62
  await tools.mem.share({ action: "revoke", ids: ["rec_..."], space: "space-team" }) // delete copies
38
63
  await tools.mem.share({ action: "transfer", path: "runbooks/staging-deploy", to: "sam@example.com" })
39
64
  ```
@@ -43,8 +68,11 @@ read. Transfer makes another person the owner of a page or folder; they must
43
68
  already be able to edit it, and you keep the access your space role gives you.
44
69
  Folder transfer pages through large folders and changes owners only, never page
45
70
  bodies. It can complete partially; a retry may need an owner or admin.
46
- An email that matches no member of the spaces you can see is refused: ask for
47
- their user id from `spaces` `members`.
71
+ Grant and transfer ask the person first, with the address as typed; the
72
+ address is looked up only after they approve. A page shared with you as editor
73
+ can be changed but not shared on: ask its owner. An email no one in your
74
+ organisation has used is refused, and nothing changes.
75
+ Too many lookups in a minute are refused too: wait, or pass their user id.
48
76
 
49
77
  ## Team spaces
50
78
 
@@ -52,10 +80,12 @@ A team space is a shared space with members and roles, set by the control plane.
52
80
  **Private** reads and writes always use the personal space. A **team** write needs
53
81
  a shared space passed with `space` or bound to the session, and editor access or
54
82
  more. The host's permission policy is consent: an answered ask, configured
55
- allow, or remembered always. Team remember, revise, page write and wiki write
83
+ allow, or remembered always. Team revise, page write and wiki write
56
84
  default to ask. If an old host cannot add default rules, it refuses team writes
57
85
  unless an explicit rule for the action is visible and says how to opt in.
58
86
  Jelly with `heldTeamWrites` uses the held Inbox. Private writes never ask.
87
+ `remember` always writes the personal space. Only when the person asks for a
88
+ memory in a team space: remember it, then `share` copy it there.
59
89
  When the tool says "allowed by your permission settings", do not claim the
60
90
  person was asked.
61
91
  List spaces or members only when the needed space or recipient is unknown; a
@@ -64,10 +94,13 @@ successful tool result is not a reason to inspect them again.
64
94
  ```js
65
95
  await tools.mem.spaces({ action: "list" }) // mem_spaces({ action: "list" })
66
96
  await tools.mem.spaces({ action: "members", space: "space-team" })
67
- await tools.mem.remember({ content: "Production deploys run only on Tuesdays", kind: "constraint", visibility: "team", space: "space-team", why: "Agreed by the platform team, 2026-11-05" })
97
+ await tools.mem.share({ action: "copy", ids: ["rec_..."], space: "space-team", rationale: "The person asked the platform team to have it" })
68
98
  ```
69
99
 
70
- `spaces` `current` says whether this session is bound to a shared space; `access`
100
+ `spaces` `current` says whether this session is bound to a shared space. Passing
101
+ `space` to a tool never binds; only the person's request does:
102
+ `spaces({ action: "current", bind: { space: "personal" } })` or a space id. A
103
+ session bound to an archived space is refused until it is rebound. `access`
71
104
  shows your role and the grants that name you. They say who can see what, never
72
105
  what the rules are: "am I allowed" is a `recall` question.
73
106