@joe-broadhead/opencode-mem 0.0.0-stage → 0.6.2

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/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Joe Broadhead
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,382 @@
1
- # Temporary Holding Version
1
+ # opencode-mem
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ [![ci](https://github.com/joe-broadhead/opencode-mem/actions/workflows/ci.yml/badge.svg)](https://github.com/joe-broadhead/opencode-mem/actions/workflows/ci.yml)
4
+
5
+ Durable private and shared-space memory for OpenCode agents.
6
+
7
+ `opencode-mem` is an OpenCode 2 plugin. It pins a small context block per
8
+ session, captures completed turns, mirrors skills into OpenCode's native
9
+ registry, and exposes recall as tools the model calls. It talks to a
10
+ TencentDB Agent Memory backend over the upstream `/v3` contract; the transport is
11
+ isolated in `src/backend/v3.js`.
12
+
13
+ **Requirements:** OpenCode **2.1.4 or newer** and Node.js **22.13 or newer** for
14
+ the repository, operations scripts, and control provisioning. The plugin refuses
15
+ older OpenCode hosts rather than degrading silently.
16
+
17
+ ## Current architecture
18
+
19
+ 1. The OpenCode plugin talks HTTPS to the public auth/gateway with a Better Auth
20
+ API key; each machine keeps its own LLM provider.
21
+ 2. The gateway verifies the caller, resolves a context from the internal control
22
+ plane, and routes `/core/*` and `/knowledge/*` to one memory cell.
23
+ 3. The control plane owns organisations, spaces, members, collections, resources,
24
+ grants, cells, and placements; the cell owns memory, wiki, code graph, and
25
+ skills.
26
+ 4. The gateway enforces the active space role, the resource catalog, cell status,
27
+ and a per-cell credential before forwarding. Client identity and key headers
28
+ are discarded.
29
+ 5. Mission Control is served from the same origin; control mode adds space,
30
+ grant, and member views. See [docs/architecture.md](docs/architecture.md).
31
+
32
+ ## Quick start
33
+
34
+ Prerequisites: Node.js 22.13+, OpenCode 2.1.4+, and a cloned repository.
35
+
36
+ ```bash
37
+ git clone https://github.com/joe-broadhead/opencode-mem.git ~/opencode-mem
38
+ cd ~/opencode-mem
39
+ npm test # every test/*.test.js suite; no network
40
+ npm run stub # http://127.0.0.1:8420, JSON storage in stub/data
41
+ ```
42
+
43
+ In another terminal, install the plugin against the simulator:
44
+
45
+ ```bash
46
+ node scripts/install.mjs --options '{"baseURL":"http://127.0.0.1:8420","user":"me"}'
47
+ opencode service restart
48
+ opencode run --auto "Call mem_status and reply with its output verbatim."
49
+ ```
50
+
51
+ The installer backs up `~/.config/opencode/opencode.json` and preserves every
52
+ other plugin. Remove it with `node scripts/install.mjs --remove`. For a
53
+ single-machine walkthrough, see [docs/local-quickstart.md](docs/local-quickstart.md).
54
+ For a team deployment, follow [docs/team-onboarding.md](docs/team-onboarding.md).
55
+
56
+ ### Daily use: load a release, not a working tree
57
+
58
+ OpenCode loads the plugin from the directory in `package`, so a working tree
59
+ there is live: an edit or a branch switch changes every session on the next
60
+ start. For daily use, export a tagged release and pin both paths to it:
61
+
62
+ ```bash
63
+ V=0.2.1
64
+ DEST=~/.local/share/opencode-mem/releases/$V
65
+ mkdir -p "$DEST" && git -C ~/opencode-mem archive "v$V" | tar -x -C "$DEST"
66
+ ```
67
+
68
+ Set the plugin `package` to `$DEST` and the instructions entry to
69
+ `$DEST/docs/agent-protocol.md`. To upgrade, export the new tag and change both
70
+ paths; to roll back, point them at the previous directory. Change the paths
71
+ rather than flipping a symlink: OpenCode reloads a plugin when its config entry
72
+ changes, and a symlink flip can stop the plugin without loading it again.
73
+
74
+ ### From npm
75
+
76
+ The plugin is published as `@joe-broadhead/opencode-mem`. The package holds the
77
+ plugin only: `index.js`, `src/`, the built-in skill, and
78
+ `docs/agent-protocol.md`. It has no runtime dependencies. Pin an exact version:
79
+
80
+ ```jsonc
81
+ { "package": "@joe-broadhead/opencode-mem@0.6.1", "options": { "controlURL": "https://memory.example.com", "token": "<key from /account>" } }
82
+ ```
83
+
84
+ The agent protocol is in the package at `docs/agent-protocol.md`. Name that
85
+ file in `instructions`, or use a release export (above) when you want both
86
+ paths under your control. The server side (gateway, control, the cell) is not
87
+ in the package; deploy it from this repository.
88
+
89
+ ## Plugin configuration
90
+
91
+ For a control-plane deployment, point `controlURL` at the **public gateway
92
+ origin**, not at the internal control service. `token` is the teammate's Better
93
+ Auth API key.
94
+
95
+ ```jsonc
96
+ {
97
+ "plugins": [
98
+ {
99
+ "package": "/opt/opencode-mem",
100
+ "options": {
101
+ "baseURL": "https://memory.example.com/core",
102
+ "knowledgeURL": "https://memory.example.com/knowledge",
103
+ "controlURL": "https://memory.example.com",
104
+ "token": "{env:MEMORY_TOKEN}",
105
+ "agent": "auto",
106
+ "captureVisibility": "private"
107
+ }
108
+ }
109
+ ]
110
+ }
111
+ ```
112
+
113
+ | Option | Default | Meaning |
114
+ |---|---|---|
115
+ | `baseURL` | `<controlURL>/core`; without a gateway `http://127.0.0.1:8420` | Memory core or gateway `/core` URL |
116
+ | `knowledgeURL` | `<controlURL>/knowledge`; without a gateway `baseURL` | Wiki / code-graph service |
117
+ | `controlURL` | `MEMORY_CONTROL_URL`; inside Jelly the Jelly account's memory origin | Public gateway origin for spaces, context, and turn capture (`/v1/capture`) |
118
+ | `token` | `MEMORY_TOKEN`; inside Jelly a Jelly token, then the pasted key | Better Auth API key. Order: [Running inside Jelly](#running-inside-jelly) |
119
+ | `capture` | `true` | Capture completed turns. `false` keeps the tools and captures nothing |
120
+ | `captureVisibility` | `private` | Completed turns stay personal unless explicitly shared. `team` writes a turn to the session's bound shared space; the gateway decides, and a session with no shared binding keeps the turn private |
121
+ | `captureSubagents` | `false` (`MEMORY_CAPTURE_SUBAGENTS`) | Capture and pin subagent (child) sessions. Off: a child's brief is never stored as a user turn, and the child gets the protocol but not the pinned block |
122
+ | `compactionCheckpoint` | follows `capture` | Write a private pre-compaction checkpoint to L0. Set it to `true` to keep checkpoints with capture off |
123
+ | `stateDir` | `~/.local/state/opencode-mem` | Spool, claims, materialised skills, log |
124
+ | `debug` | `false` | Add DEBUG lines to the log and mirror every line to stderr. Leave it off in daily use |
125
+ | `debugFile` | `stateDir/debug.log` | Plugin log. INFO, WARN, and ERROR are always written; mode 0600; rotates at 5 MB into `debug.log.1`. Query, prompt, and memory text are never logged |
126
+
127
+ There is no team, private-team, user-key, or admin-URL setting. A control-plane
128
+ deployment gets every container from the resolved space context. Without
129
+ `controlURL`, and outside Jelly, the plugin runs in local direct mode against
130
+ one fixed `local` scope for the bundled simulator; the space, grant, and member
131
+ tools report that a control plane is not configured. With a gateway but no key,
132
+ the plugin loads and every memory tool answers "Memory is unavailable: …" with
133
+ the reason; nothing is captured. The full option list and defaults are in
134
+ `src/config.js`.
135
+
136
+ ## Running inside Jelly
137
+
138
+ Jelly runs each agent in its own OpenCode 2.2.5 engine. The package is `@joe-broadhead/opencode-mem`, the name Jelly
139
+ keys plugins and their secrets by, and its `package.json` carries a `jelly`
140
+ declaration. Inside Jelly the plugin is opt-in: a host has it installed, and a
141
+ person adds it to an agent.
142
+
143
+ **The `memory` resource.** The declaration names `"resources": ["memory"]`.
144
+ Jelly gives an agent's engine the identity accessor for a resource only when
145
+ one of the plugins given to that agent declares it, and its host answers
146
+ `invalid_target` for any other name. `resources` is not in `requires`, on
147
+ purpose: a Jelly that does not know the field ignores it and still loads the
148
+ plugin, which then uses the pasted key.
149
+
150
+ **Credentials, first match wins** (`src/credentials.js`):
151
+
152
+ 1. the `token` option or `MEMORY_TOKEN` (not set inside Jelly; the engine starts
153
+ with an empty environment);
154
+ 2. Jelly's identity accessor, `globalThis[Symbol.for("jelly.identity")]`, when
155
+ its `resources()` lists `memory`: the host is signed in to a Jelly account
156
+ whose Jelly ID offers `memory`, and the agent was given this plugin. The
157
+ plugin asks `token("memory")` for a ten-minute token, keeps it in memory
158
+ until 60 s before it expires, and asks again once when the gateway answers
159
+ `401`;
160
+ 3. the **Memory key** setting: the key pasted from the memory site's `/account`
161
+ page, read with
162
+ `globalThis[Symbol.for("jelly.plugin-secrets")].get("@joe-broadhead/opencode-mem", "token")`.
163
+
164
+ **When Jelly refuses the token.** `token("memory")` rejects with a code. Jelly's
165
+ host maps Jelly ID's `400` to `invalid_target`, `401` to `not_enrolled`, `403`
166
+ to `access_denied`, and everything else, a `503` included, to `unavailable`, so
167
+ the plugin cannot tell an outage from Jelly ID turning memory off. The host
168
+ holds each refusal for 30 s, and so does the plugin: Jelly is not asked again
169
+ until the 30 s pass.
170
+
171
+ | Code | What the request does |
172
+ |---|---|
173
+ | `invalid_target`, `not_enrolled`, `unavailable` | Uses the pasted key, when one is saved. With no key, it fails with "this agent's Jelly sign-in can't be used for memory: … (`<code>`), and no memory key is saved in the plugin's settings"; a finished turn is spooled for later |
174
+ | `access_denied` | Fails: "the Jelly account is disabled or marked for deletion (access_denied); a saved memory key is not used in its place". No fallback |
175
+
176
+ Why no fallback on `access_denied`: Jelly says the account behind this agent is
177
+ disabled or about to be deleted. Writing on with a pasted key would get round
178
+ the switch that stops that account, so the plugin stops instead. A `401` from
179
+ the gateway never switches sources: a refused Jelly token is replaced by a new
180
+ Jelly token or not at all, and a refused pasted key is not retried.
181
+
182
+ `mem_status` and `/mem-status` show the credential in use, for example
183
+ `credential: plugin-secret (Jelly refused a memory token: unavailable; Jelly is
184
+ asked again within 30 s)`, and the log has one warning per refusal (its code,
185
+ never a token).
186
+
187
+ **Accepted risk.** If a person's Jelly sign-in and pasted key belong to two
188
+ different memory users, a request that falls back writes as the key's user,
189
+ into that user's memory, until Jelly answers again. Paste a key from the same
190
+ account you sign in to Jelly with.
191
+
192
+ **Gateway origin:** the **Memory address** setting (`controlURL`), else the
193
+ `url` of the identity accessor's `memory` resource, during a fallback too.
194
+ `baseURL` and `knowledgeURL` default to `<origin>/core` and `<origin>/knowledge`.
195
+
196
+ A token is never logged, spooled, or written to a file. With no credential the
197
+ plugin still loads and registers its nine tools; each answers one sentence
198
+ saying why memory is unavailable, and nothing is captured, spooled, or sent.
199
+
200
+ **Icon.** The declaration's `icon` is `assets/icon.svg`, shipped in the
201
+ package: a flat brain mark on a square `viewBox`, made only of the elements
202
+ and attributes Jelly's `cleanPluginIcon` keeps. Jelly drops an icon that does
203
+ not clean, without an error, and draws a monogram instead, so
204
+ `npm run check:jelly` runs the file through Jelly's own cleaner.
205
+
206
+ **Settings** (`jelly.contributes.settings`):
207
+
208
+ | Key | Type | Meaning |
209
+ |---|---|---|
210
+ | `controlURL` | string | Memory address. Empty: the Jelly account's memory origin |
211
+ | `capture` | boolean | On by default. Off: the tools still work and nothing is captured, the compaction checkpoint included |
212
+ | `token` | secret | Memory key, for a host without a Jelly sign-in that offers memory, and the fallback when Jelly refuses a token (not after `access_denied`). A saved key reaches the plugin at the engine's next start |
213
+
214
+ **Tools and permissions.** Each tool is declared as `name: "mem.<tool>"`,
215
+ `permission: "mem_<tool>"`, `effect: "allow"`:
216
+
217
+ | Tool | Permission | readOnly |
218
+ |---|---|---|
219
+ | `mem.recall`, `mem.status`, `mem.spaces`, `mem.grants`, `mem.members` | `mem_recall`, `mem_status`, `mem_spaces`, `mem_grants`, `mem_members` | `true` |
220
+ | `mem.wiki`, `mem.remember`, `mem.forget`, `mem.promote` | `mem_wiki`, `mem_remember`, `mem_forget`, `mem_promote` | `false` |
221
+
222
+ Why this mapping:
223
+
224
+ - **Permission is the engine's tool id.** OpenCode 2.2.5 names a tool
225
+ `<namespace>_<name>`, and a tool that sets no `options.permission` (none of
226
+ these does) is asked for under that id. Jelly's core plugin asserts
227
+ `tool.options.permission ?? call.tool`, and Jelly's schema derives the same id
228
+ (`name.replaceAll(".", "_")`). Tavily's declaration follows the same rule:
229
+ `tavily.tavily_search` → `tavily_tavily_search`. So a person's Allow, Ask, or
230
+ Off on the plugin's card, and the read-only helpers' fence, act on the id the
231
+ engine really checks.
232
+ - **Effect `allow`.** A declared `ask` becomes a default rule on that
233
+ permission, but the engine asks only when a tool asserts its permission, and
234
+ the memory tools do not assert their own id. An `ask` would be a rule the
235
+ engine never consults on the main agent. A declared `allow` writes nothing.
236
+ - **`readOnly: false` for wiki, remember, forget, and promote**, because they
237
+ write. Jelly denies them to the read-only helpers (researcher, reviewer).
238
+ `mem_wiki` reads too, but it is one tool, so the helpers lose its reads.
239
+
240
+ **Team writes ask inside Jelly.** A team-visible write asserts the plugin's own
241
+ approval actions, with the space as the resource: `memory.remember`,
242
+ `memory.forget`, `memory.promote`, `memory.promote.revoke`, `wiki.write`.
243
+ Jelly's default rules (`agents/default/opencode.jsonc`) set all five to `ask`,
244
+ so a person approves each write to a shared space. Private writes, the default,
245
+ assert nothing and never ask. These five action names are a contract with
246
+ Jelly: do not rename one, or add one, without telling Jelly, or a team write
247
+ runs without a prompt there.
248
+
249
+ **`asks`.** The declaration lists the same five actions in `"asks"`, so Jelly
250
+ can read from the plugin, not only from its own default rules, which run-time
251
+ actions to ask a person about. Like `resources`, it is additive and not in
252
+ `requires`: a Jelly that does not know the field leaves it out and still loads
253
+ the plugin. `test/jelly-declaration.test.js` and `npm run check:jelly` both
254
+ compare `asks` with the actions the tools really assert
255
+ (`scripts/approval-actions.mjs`), so the two cannot drift apart.
256
+
257
+ The declaration has no sign-ins: the Jelly account is the host's sign-in, and
258
+ the pasted key is a secret setting. `npm run check:jelly -- <Jelly checkout>`
259
+ parses the declaration with Jelly's own `PluginDeclarationSchema`, checks that
260
+ `resources` is kept and not required, that `asks` is not required and is kept
261
+ when that Jelly knows it, and runs the icon through Jelly's
262
+ `cleanPluginIcon`; `test/jelly-declaration.test.js` checks the same in CI,
263
+ with the schema and the cleaner restated.
264
+
265
+ **One memory per person.** Every Jelly engine runs the OpenCode agent `agent`,
266
+ so a person's Jelly agents read and write one personal memory, under agent
267
+ `agent` in their own personal container. That memory is separate from the
268
+ persona and scenarios of their other OpenCode agents (`build`, `plan`, …),
269
+ which are keyed by agent name. `agent` is not a reserved name.
270
+
271
+ ## Spaces, grants, and memory
272
+
273
+ Each user has one personal space, in a memory container of its own: upstream
274
+ scenarios and persona are keyed by container plus agent, so only a container of
275
+ its own keeps them private whatever agent names people use. Legacy personal
276
+ spaces that share one container keep a distinct personal agent per user
277
+ ([docs/design/adr-personal-containers.md](docs/design/adr-personal-containers.md)). A shared space maps to one upstream container and a set of control-plane
278
+ grants. Membership and placement are control-plane data; the
279
+ plugin never invents or upgrades a role.
280
+
281
+ | Tool | Use |
282
+ |---|---|
283
+ | `mem_recall` | Search L0/L1 memory before re-deriving context. It searches the declared task first and widens to the whole space on a miss, labelling each hit. In control mode it searches the session's space (a bound shared space, otherwise personal) or an explicit `space`; `visibility: "private"` forces the personal space. |
284
+ | `mem_wiki` | Read, search, create, or update wiki and code-graph knowledge. |
285
+ | `mem_remember` | Store a rule, decision, preference, or procedure. Private by default. |
286
+ | `mem_forget` | Delete atoms and raw turns by id, under the agent and session that wrote them, with the `mem_remember` rows that hold only that text, and list every other stored copy with ids; or erase a phrase from the L2 scenarios and L3 persona (preview, then `confirm`). Irreversible. |
287
+ | `mem_promote` | Share private memory with a shared space as a copy (one wiki, with provenance), or revoke a share. |
288
+ | `mem_status` | Backend health, active scope, layer counts, skills, and spool. |
289
+ | `mem_spaces` | List personal and shared spaces, or show the active context. |
290
+ | `mem_grants` | List the grants that apply to you in a space. |
291
+ | `mem_members` | List a space's member roster. |
292
+
293
+ Private writes always go to the personal space. A team write needs an explicitly
294
+ selected or session-bound shared space with editor-or-higher access, and asks for
295
+ approval. There is no live per-atom grant: `mem_promote` copies private memory
296
+ into one new wiki in a shared space, and `mem_promote` with `revoke` deletes the
297
+ copy and reads it back ([ADR](docs/design/adr-sharing-semantics.md)).
298
+ Collection and resource grants cover wikis, code graphs, and skills, never
299
+ memory; a different memory audience needs its own space
300
+ ([ADR](docs/design/adr-collection-scope.md)).
301
+
302
+ Agent guidance has two layers. [docs/agent-protocol.md](docs/agent-protocol.md)
303
+ is the short always-on protocol; load it through `AGENTS.md` or the top-level
304
+ `instructions` array in `opencode.json`. The bundled
305
+ [mem.usage skill](skills/mem-usage/SKILL.md) is the detailed playbook with a
306
+ decision table, worked workflows, and failure handling. They are related but not
307
+ identical: the protocol is the rule layer, the skill is the reference.
308
+
309
+ ## Mission Control
310
+
311
+ The auth service serves the console at `/console/` and its API at
312
+ `/api/console/*`. It shows memory layers, wiki pages and search, a
313
+ force-directed wiki graph, code indexes, pipeline state, the crew manifest, and
314
+ spaces, collections, resources, grants, and members.
315
+ Grant and member mutations go through the control plane. The browser holds only
316
+ a Better Auth session or API key; service keys stay server-side. A gateway
317
+ with Jelly ID as its only way in has no sign-in page: the console and `/login`
318
+ say that people use Memory from Jelly. See [docs/mission-control.md](docs/mission-control.md).
319
+
320
+ ## Operations
321
+
322
+ | Task | Where |
323
+ |---|---|
324
+ | Load the always-on memory protocol | [docs/agent-protocol.md](docs/agent-protocol.md) |
325
+ | Specify or run memory behavior evals | [docs/evals/README.md](docs/evals/README.md) |
326
+ | Decide what belongs in memory, wiki, or a tracker | [docs/memory-primitives.md](docs/memory-primitives.md) |
327
+ | Understand prompt size and cache behavior | [docs/tokenomics.md](docs/tokenomics.md) |
328
+ | Compare public memory benchmarks and our derived subset | [docs/evals/public-benchmarks.md](docs/evals/public-benchmarks.md) |
329
+ | Deploy, size, back up, restore, or recover a cell | [docs/deployment.md](docs/deployment.md) |
330
+ | Understand the public/private boundary | [docs/trust-model.md](docs/trust-model.md) |
331
+ | PostgreSQL WAL archiving, PITR, and restore drills (greenfield; no SQLite row copy) | [docs/postgres-pitr.md](docs/postgres-pitr.md) |
332
+ | Control-plane API and migrations | [control/README.md](control/README.md) |
333
+ | Compose, host, and observability assets | [deploy/README.md](deploy/README.md) |
334
+ | Diagnose a failure | [docs/troubleshooting.md](docs/troubleshooting.md) |
335
+ | Documentation index | [docs/README.md](docs/README.md) |
336
+
337
+ Control-plane backup and restore cover control metadata only. Memory, wiki, code
338
+ graphs, skills, auth sessions, and cell volumes are separate backup sets:
339
+
340
+ ```bash
341
+ npm run ops:backup -- --db ./control/control.db --out ./backups/control --retain 14
342
+ npm run ops:restore -- --backup ./backups/control/<backup-dir> --target ./control/control.db --dry-run
343
+ npm run ops:drill
344
+ ```
345
+
346
+ ## Tests
347
+
348
+ ```bash
349
+ npm test # every test/*.test.js: plugin, gateway, console, scripts, ops, load, eval grader
350
+ npm run test:control # control API, policy, storage, provisioning, and migrations
351
+ npm run test:ops # subset of npm test: control backup, restore, retention, and drill
352
+ npm run build:ui # build the Mission Control SPA
353
+ npm run check:syntax # parse every JavaScript module
354
+ npm run check:docs # relative links and anchors in tracked Markdown
355
+ npm run check:docker
356
+ npm run check:compose
357
+ npm run eval:controls # offline: 62 grader controls
358
+ npm run eval:core # live: 38 core scenarios (needs model credentials)
359
+ npm run eval:extended # live: 103 private memory scenarios
360
+ npm run eval:public # live: 22 LongMemEval-derived cases
361
+ npm run eval:closed-book # live: 10 empty-memory leakage controls
362
+ npm run e2e # live: six eval scenarios against a temp stub and fake control plane
363
+ npm run verify:edge # deployed edge: every plugin read path reaches a service
364
+ ```
365
+
366
+ Every `npm run` alias is listed in [CONTRIBUTING.md](CONTRIBUTING.md#npm-scripts).
367
+
368
+ The bundled simulator proves contract handling and lifecycle wiring; it does not
369
+ prove the real backend's extraction or curation quality. Extraction and curation
370
+ are asynchronous and batched: a same-space recall can return the raw L0 write
371
+ immediately, but the distilled L1/L2 view can lag.
372
+
373
+ ## Contributing and security
374
+
375
+ See [CONTRIBUTING.md](CONTRIBUTING.md) for development and checks, and
376
+ [SECURITY.md](SECURITY.md) for the trust model and private vulnerability
377
+ reporting. Do not put credentials, customer data, or private transcripts in
378
+ team-visible memory.
379
+
380
+ ## License
381
+
382
+ MIT
package/SECURITY.md ADDED
@@ -0,0 +1,135 @@
1
+ # Security policy
2
+
3
+ ## Supported versions
4
+
5
+ | Component | Supported |
6
+ |---|---|
7
+ | `opencode-mem` | 0.6.x |
8
+ | OpenCode | 2.1.4 or newer |
9
+ | Node.js | 22.13 or newer |
10
+ | Memory core / hub | `agentmemory/memory-core` and `memory-hub` 2.0.0-beta.1 (image ids `f9b286246d0e`, `99c234f606be`), pinned by image id; see [CHANGELOG.md](CHANGELOG.md) |
11
+
12
+ Older OpenCode versions are refused at plugin setup because the plugin uses the
13
+ V2 plugin context and `ctx.permission.assert`.
14
+
15
+ ## Reporting a vulnerability
16
+
17
+ Use GitHub's private vulnerability reporting on this repository:
18
+
19
+ https://github.com/joe-broadhead/opencode-mem/security/advisories/new
20
+
21
+ Do not open a public issue with a working exploit, a live token, a private
22
+ domain, or a customer's memory content.
23
+
24
+ Include:
25
+
26
+ - the affected version and commit;
27
+ - whether the issue affects the plugin, the gateway/auth service, the control
28
+ plane, the console, a cell, or a deployment script;
29
+ - a minimal reproduction with placeholder identities and domains;
30
+ - the impact you believe it has.
31
+
32
+ ## Security model
33
+
34
+ The full boundary and residual risks are in [docs/trust-model.md](docs/trust-model.md).
35
+ This is the summary.
36
+
37
+ ### Public and internal surfaces
38
+
39
+ - The edge and the auth/gateway are the only public application surface. TLS
40
+ terminates at the edge.
41
+ - The control plane is internal: loopback or a private network, no public DNS,
42
+ no browser CORS, no cookies.
43
+ - Memory cells (core + hub) and PostgreSQL are internal. A cell URL and
44
+ `secret_ref` are server-side routing data.
45
+ - The browser holds a Better Auth session (console and `/account` only); the
46
+ plugin and CLI hold a Better Auth API key, or inside a Jelly host a
47
+ ten-minute Jelly ID resource token for the memory resource, and the API key
48
+ a person pasted, used while Jelly refuses a token (never after
49
+ `access_denied`). None of them ever holds a gateway, knowledge, admin, or
50
+ per-cell key.
51
+
52
+ ### Credentials
53
+
54
+ | Credential | Lives in | Purpose |
55
+ |---|---|---|
56
+ | Better Auth API key | Client | Authenticates one user to the gateway; expires after `AUTH_KEY_TTL_DAYS` (90); revocable on `/account` or with `deploy/auth/scripts/revoke-user-keys.mjs` |
57
+ | Jelly ID resource token | Client (a Jelly host, in memory only) | Authenticates the host's owner to the gateway for ten minutes; verified with the issuer's Ed25519 keys, audience-bound; at the gateway a refused one never falls back to another credential kind ([docs/design/adr-personal-containers.md](docs/design/adr-personal-containers.md)). The plugin's own fallback to a pasted key is a separate request with that key ([README](README.md#running-inside-jelly)) |
58
+ | `CONTROL_TOKEN` | Gateway | Authenticates the gateway to control; must equal `CONTROL_SERVICE_TOKEN` |
59
+ | `CONTROL_SERVICE_TOKEN` | Control service | Verifies the gateway's `x-control-user` assertion; never grants admin |
60
+ | `CONTROL_ADMIN_TOKEN` | Operator/infrastructure, the exporter, the `cell-health` job | Cell and placement administration; separate from the service token |
61
+ | `CONTROL_CELL_SECRETS` entry | Gateway, and the `cell-health` job in the same image | Per-cell bearer, selected only by control's `secret_ref`; the checker sends it only to that cell's `/health` |
62
+
63
+ A configured control plane requires `CONTROL_SERVICE_TOKEN`. Without it,
64
+ `x-control-user` is trusted without a bearer, which is acceptable only for
65
+ loopback/tests. The service refuses to start if the service and admin tokens are
66
+ equal, and a service token never sets `admin`.
67
+
68
+ ### Enforcement
69
+
70
+ - The gateway derives identity from the verified API key (data plane, context,
71
+ `/v1/*`) or session (console), strips client identity, key, `x-control-*`,
72
+ and hop-by-hop headers, and rewrites body identity at every depth.
73
+ - The active space role gates path allowlists: viewers may read; editors and
74
+ above may also call the write allowlist; any other upstream route is
75
+ `403 endpoint_not_allowed` for every role.
76
+ - Control-owned upstream routes (`/v3/meta/user/*`, `/v3/meta/team/*` except
77
+ `list`, `/v3/acl/*`, `/v3/admin/*`, and others) return `endpoint_managed`.
78
+ - Every wiki or code-graph id named anywhere in a request is batch-authorized
79
+ against the control `resources` catalog. Any denied id returns
80
+ `403 resource_forbidden`. Container-wide lists are filtered through the same
81
+ catalog, and JSON responses are stripped of placement fields.
82
+ - Registering a resource needs proof from the cell that the asset lives in that
83
+ space's container (and, in a personal space, belongs to the caller); otherwise
84
+ `403 resource_not_owned`.
85
+ - Cells run with `V3_STRICT_ISOLATION=1`. Per-cell credentials are resolved
86
+ locally; a missing reference is `503 cell_credential_unavailable`, and a cell
87
+ without a routing URL is `503 cell_unavailable`.
88
+ - The console derives scope from the verified identity. Its only writes are
89
+ grant create/revoke and member invite, role change, and removal; the control
90
+ plane decides every role. Writes are CSRF-checked (same-origin JSON only).
91
+ - Limits: `/api/auth/*` bodies are capped at 64 KiB and rate limited per client
92
+ address; key-authenticated requests are limited per user and failed key
93
+ verifications per address; Better Auth's limiter is on. The shipped
94
+ Caddyfiles cap bodies at the edge as well.
95
+ - With Google sign-in, `GOOGLE_HD` is required (or an explicit `*`); the dev
96
+ password refuses to start on an https origin. The gateway refuses to start
97
+ with no way in at all; Jelly ID alone is enough, and then `/login` offers no
98
+ sign-in.
99
+
100
+ ### No links-file path
101
+
102
+ `CONTROL_URL` and `CONTROL_TOKEN` are mandatory. The gateway refuses to start
103
+ without them, always resolves identity and placement from the control plane, and
104
+ has no links-file, `/admin/*`, or legacy team fallback. The removed path is not
105
+ a deployment option.
106
+
107
+ ### Not protected
108
+
109
+ - A per-cell key is cell-wide. Strict isolation separates service ids, not
110
+ people.
111
+ - Private memory is isolated by `user_id`/personal agent, not encrypted per user.
112
+ Operators, cell backups, and the configured LLM provider can read content.
113
+ - Data-plane reads are not audited; control mutations, session bindings, and
114
+ placement changes are.
115
+ - The repository does not provide MFA or a WAF. Rate limits are in-process
116
+ windows that reset on restart; stock Caddy has no rate-limit module.
117
+ - The Google domain check runs only at sign-in. Offboarding needs the revoke
118
+ script (keys and sessions) plus control membership removal.
119
+ - Backups are not automatically encrypted or signed.
120
+ - A compromised gateway can assert any control user and resolve any configured
121
+ cell key.
122
+
123
+ ## Secrets in this repository
124
+
125
+ This repository must not contain:
126
+
127
+ - real gateway, knowledge, control-admin, provider, cell, or OAuth keys;
128
+ - `auth.env`, `.env`, local databases, certificates, or DNS credentials;
129
+ - real domains, IP addresses, team ids, user ids, or personal email addresses in
130
+ tests and examples.
131
+
132
+ Use `example.com`, `memory.example.com`, `team-…`, and `usr-…` in examples.
133
+
134
+ If a secret is committed, rotate it first. Removing it from the current tree is
135
+ not enough because it remains in Git history.
@@ -0,0 +1,14 @@
1
+ <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64">
2
+ <rect width="64" height="64" rx="14" fill="#3B3486"/>
3
+ <g fill="none" stroke="#F4F1FF" stroke-width="3.5" stroke-linecap="round" stroke-linejoin="round">
4
+ <path d="M32 15C28.5 11 21.5 11.5 19.5 17C14.5 17.5 11.5 22.5 14 27C10 30 10.5 36 15 38C13.5 43.5 18 48 23 47C25 51 30 51.5 32 48"/>
5
+ <path d="M32 15C35.5 11 42.5 11.5 44.5 17C49.5 17.5 52.5 22.5 50 27C54 30 53.5 36 49 38C50.5 43.5 46 48 41 47C39 51 34 51.5 32 48"/>
6
+ <path d="M32 15V48"/>
7
+ <path d="M19.5 17C20.5 20.5 23.5 22 26.5 21"/>
8
+ <path d="M14 27C17.5 28.5 21 27.5 22.5 25"/>
9
+ <path d="M15 38C18 36.5 21.5 37 24 39.5"/>
10
+ <path d="M44.5 17C43.5 20.5 40.5 22 37.5 21"/>
11
+ <path d="M50 27C46.5 28.5 43 27.5 41.5 25"/>
12
+ <path d="M49 38C46 36.5 42.5 37 40 39.5"/>
13
+ </g>
14
+ </svg>