@joe-broadhead/opencode-mem 0.8.5 → 0.9.0

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 (52) hide show
  1. package/CHANGELOG.md +429 -0
  2. package/README.md +114 -61
  3. package/docs/agent-protocol.md +67 -177
  4. package/package.json +1351 -98
  5. package/skills/mem.pages/SKILL.md +143 -0
  6. package/skills/mem.sharing/SKILL.md +82 -0
  7. package/skills/mem.sources/SKILL.md +93 -0
  8. package/skills/mem.usage/SKILL.md +118 -492
  9. package/src/backend/records.js +285 -0
  10. package/src/bootstrap.js +49 -45
  11. package/src/call-shapes.js +41 -10
  12. package/src/collector-lock.js +162 -0
  13. package/src/collector-service.js +441 -0
  14. package/src/collector.js +381 -0
  15. package/src/commands.js +3 -3
  16. package/src/config.js +12 -1
  17. package/src/curation.js +1 -1
  18. package/src/permissions.js +18 -2
  19. package/src/protocol.js +29 -20
  20. package/src/recall.js +104 -27
  21. package/src/records-store.js +280 -120
  22. package/src/records.js +63 -11
  23. package/src/runtime.js +23 -14
  24. package/src/skills.js +44 -18
  25. package/src/sources.js +58 -0
  26. package/src/spaces.js +93 -10
  27. package/src/tools/aliases.js +163 -0
  28. package/src/tools/commitments.js +12 -9
  29. package/src/tools/index.js +88 -19
  30. package/src/tools/ingest.js +277 -0
  31. package/src/tools/knowledge.js +6 -1
  32. package/src/tools/memory.js +640 -210
  33. package/src/tools/page.js +411 -0
  34. package/src/tools/recall.js +363 -112
  35. package/src/tools/records-kit.js +142 -0
  36. package/src/tools/share.js +1012 -0
  37. package/src/tools/shared.js +8 -1
  38. package/src/tools/spaces.js +431 -143
  39. package/src/tools/status.js +87 -58
  40. package/src/tools/wiki.js +2 -2
  41. package/src/views/contracts.js +273 -3
  42. package/src/views/records-reads.js +675 -0
  43. package/src/views/rpc.js +17 -100
  44. package/src/views/shape.js +61 -0
  45. package/views/commitments.html +4 -0
  46. package/views/graph.html +753 -0
  47. package/views/home.html +11 -5
  48. package/views/journal.html +621 -0
  49. package/views/memory.html +7 -1
  50. package/views/pages.html +636 -0
  51. package/views/review.html +406 -0
  52. package/views/today.html +309 -0
@@ -0,0 +1,142 @@
1
+ /**
2
+ * What the records-backed tools (recall, remember, revise, page) share: the
3
+ * records call in a resolved space, id shapes, record lines, and paths
4
+ * (docs/design/memory-v1-contracts.md §2.3, §4.1).
5
+ *
6
+ * No approval action is named here: the tools that ask name their action
7
+ * where they ask, so `scripts/approval-actions.mjs` reads it there.
8
+ */
9
+ import { oneLine } from "../util.js"
10
+
11
+ /** `rec_` and a 26-character Crockford ULID, minted by the records service. */
12
+ export const RECORD_ID = /^rec_[0-9A-HJKMNP-TV-Z]{26}$/
13
+ /** An id the core could have minted (atoms are `m_<ms>_<hex>` on the deployed core): no spaces, no path, at most 128 characters. */
14
+ export const CORE_ID = /^[A-Za-z0-9][A-Za-z0-9_.:-]{2,127}$/
15
+ /** The core's turn ids: `msg-<hex>` (conversation/add) and `msg_<ms>_<hex>` (the recorder). */
16
+ export const TURN_ID = /^msg[-_]/
17
+ /** A page path: lower-case segments, at most four (§2.3). */
18
+ export const PAGE_PATH = /^[a-z0-9][a-z0-9-]{0,63}(\/[a-z0-9][a-z0-9-]{0,63}){0,3}$/
19
+ /** Memory types, the `kind` remember writes and recall filters on. */
20
+ export const MEMORY_TYPES = Object.freeze(["fact", "decision", "constraint", "preference", "procedure"])
21
+ export const PAGE_TYPES = Object.freeze(["person", "project", "team", "topic", "runbook", "decision", "glossary", "journal", "index"])
22
+
23
+ /** The page type a path's folder implies, by the vault conventions (§2.3). */
24
+ export function pageTypeFor(path) {
25
+ const value = String(path ?? "")
26
+ if (value === "index") return "index"
27
+ const folder = value.split("/")[0]
28
+ return (
29
+ {
30
+ people: "person",
31
+ projects: "project",
32
+ teams: "team",
33
+ topics: "topic",
34
+ runbooks: "runbook",
35
+ decisions: "decision",
36
+ journal: "journal",
37
+ glossary: "glossary",
38
+ }[folder] ?? "topic"
39
+ )
40
+ }
41
+
42
+ /** What a build without a records client answers (code `records_missing`). */
43
+ export const RECORDS_MISSING_MESSAGE =
44
+ "RECORDS_UNAVAILABLE: this plugin build has no records client, so memories, pages and commitments cannot be reached. Next step: update opencode-mem."
45
+
46
+ /** The records client, or an error the tool can answer with. */
47
+ export function recordsClient(toolkit) {
48
+ const client = toolkit.runtime?.recordsClient
49
+ if (!client || typeof client.call !== "function") throw Object.assign(new Error(RECORDS_MISSING_MESSAGE), { code: "records_missing" })
50
+ return client
51
+ }
52
+
53
+ /**
54
+ * One records call in a resolved space. The session is never sent: a space
55
+ * and a session sent together bind the session to that space at the gateway,
56
+ * so a private write would move a session bound to a shared space. The
57
+ * record's `source.session` carries the session instead.
58
+ */
59
+ export async function callRecords(toolkit, method, body, spaceContext, scoped, options = {}) {
60
+ return recordsClient(toolkit).call(method, body, {
61
+ scope: scoped,
62
+ space: spaceContext?.space_id ?? scoped?.space_id,
63
+ ...(options.timeoutMs ? { timeoutMs: options.timeoutMs } : {}),
64
+ })
65
+ }
66
+
67
+ /**
68
+ * A space the person reaches only through a page or folder grant: control
69
+ * answers its context with 403 `space_role_required`, so it cannot be
70
+ * resolved there. When the caller named that space, its records are still
71
+ * reachable through the gateway, which resolves the grant from
72
+ * `x-mem-space-id`. Answers the resolution unchanged otherwise.
73
+ */
74
+ export function grantedSpace(input, resolved) {
75
+ const requested = String(input?.space ?? "").trim()
76
+ if (!requested || !resolved?.error || !/space_role_required/.test(String(resolved.error))) return resolved
77
+ return { context: { space_id: requested, space_kind: "granted", role: "grant" }, granted: true, refusal: resolved.error }
78
+ }
79
+
80
+ /** Record ids remembered with their space, per toolkit (one process), at most. */
81
+ const RECORD_SPACES_MAX = 2_000
82
+
83
+ /**
84
+ * Remember the space a record id was seen in (recall, remember, page), so a
85
+ * later revise of that id acts in its space without a space argument.
86
+ */
87
+ export function noteRecordSpace(toolkit, id, spaceContext) {
88
+ const space = spaceContext?.space_id
89
+ if (!RECORD_ID.test(String(id ?? "")) || !space || spaceContext?.space_kind === "granted") return
90
+ const seen = (toolkit.recordSpaces ??= new Map())
91
+ seen.delete(id)
92
+ seen.set(id, String(space))
93
+ if (seen.size > RECORD_SPACES_MAX) seen.delete(seen.keys().next().value)
94
+ }
95
+
96
+ /** The space a record id was last seen in, or undefined. */
97
+ export function recordSpace(toolkit, id) {
98
+ return toolkit.recordSpaces?.get(String(id ?? ""))
99
+ }
100
+
101
+ /** The first sentence of a text, as a record's title (at most 120 characters). */
102
+ export function titleFrom(text) {
103
+ const clean = String(text ?? "").replace(/\s+/g, " ").trim()
104
+ const sentence = clean.match(/^.{1,200}?[.!?](?=\s|$)/)?.[0] ?? clean
105
+ return oneLine(sentence, 120)
106
+ }
107
+
108
+ /** "2026-11-08" from an ISO time. */
109
+ export function dateOf(value) {
110
+ return String(value ?? "").slice(0, 10) || "unknown-date"
111
+ }
112
+
113
+ /**
114
+ * Why a version was written, from `records.history`: its `change` (the
115
+ * reason given, else what the change did), in a few words.
116
+ */
117
+ export function changeNote(version) {
118
+ const change = version?.change && typeof version.change === "object" ? version.change : {}
119
+ if (change.reason) return String(change.reason)
120
+ if (change.action === "move" && change.from) return `moved from ${change.from}`
121
+ if (change.action === "append" && change.section) return `appended to ## ${change.section}`
122
+ if (change.action === "link_rewrite" && change.from) return `links to ${change.from} rewritten`
123
+ if (change.action === "superseded" && change.by_record) return `superseded by ${change.by_record}`
124
+ return change.action ? String(change.action) : ""
125
+ }
126
+
127
+ /** The ids in a `records.history` lineage list (`[{id, …}]`). */
128
+ export function lineageIds(list) {
129
+ return (Array.isArray(list) ? list : [])
130
+ .map((entry) => (entry && typeof entry === "object" ? entry.id : entry))
131
+ .filter((id) => typeof id === "string" && id)
132
+ }
133
+
134
+ /** One record as one line (`src/recall.js`): recall, lists and answers share it. */
135
+ export { recordLine } from "../recall.js"
136
+
137
+ /** Say what a records failure means for a write, in one sentence, and that nothing changed. */
138
+ export function notWritten(error, verb = "stored") {
139
+ const code = error?.code
140
+ if (code === "refused") return `not ${verb}: the records service refused it (${oneLine(error.what ?? error.message, 300).replace(/^[^:]+: /, "")}). Nothing was ${verb}.`
141
+ return ""
142
+ }