@securecoms/agent-bridge 0.28.2 → 0.29.0

package/README.md

@@ -705,99 +705,196 @@ including its key). Each proxied call is metered server-side
 
 ---
 
-## Markdown notes (0.27.0)
-
-SecureComs-runtime agents keep short notes of what the owner asks them to
-remember, in the owner's private chat only. The runtime saves a note with the
-`memory_note` tool, and the bridge stores only a quote of the owner's own
-current message. Each note is sealed per row in `bridge-state.db` (schema
-v10) and is delivered only to the runtime's `/v1/ws` socket, never to a
-harness, HTTP, SSE, a room, another chat or the voice fast path.
+## Unified memory (0.29.0)
+
+<!-- [COPY, NEW] Approved by Eric 2026-10-11 (plan Task 37). -->
+
+Bridge 0.29.0 replaces the Markdown notes of 0.27 and the semantic memory of
+0.28 with one memory. In this release it works in the owner's private chat
+only. Rooms and other people's private chats are not remembered.
+
+**What the agent remembers.**
+
+- Each message the owner types in their private chat. A message that looks
+  like a password or a key is not saved at all.
+- What the owner says on a call in their private chat, when the bridge gets
+  the turn as transcribed speech from a relay that the server verified as the
+  owner. A spoken turn that arrives before the bridge has its runtime config
+  after a restart is not saved. Spoken words cannot be pinned, and a call
+  cannot forget.
+- The agent's own replies in that chat, as reference material. A message the
+  agent sends that does not reply to a message is not saved.
+- Pinned facts. The owner asks the agent to pin a fact, and the bridge posts
+  `Pinned: "<fact>" Say "forget that" to remove it.` in the chat. Each word
+  that carries meaning must be a word the owner typed. Words spoken on a call
+  do not count. At most 200 pinned facts, each at most 400 characters.
+- "Forget that". The owner types it in their private chat. The agent removes
+  one memory shown with that message, and the bridge posts
+  `Forgot: "<text>"`. The agent makes one change (a pin or a forget) per
+  owner message.
+
+**Where it is kept.** Each memory is sealed per row in `bridge-state.db`
+(schema v12) on the agent's machine. The bridge delivers memories only to the
+`/v1/ws` socket of a runtime that declares `memory_unified` in its hello. A
+harness socket never receives them. The model provider sees the memories
+delivered with each turn. Beside the pinned facts, a typed turn gets at most
+10 memories and a voice turn at most 3. The bridge waits up to 600 ms for a
+typed turn's memory search and up to 250 ms for a voice turn's.
+
+**Limits.** The limit is 2 GB or 100,000 memories, whichever comes first.
+When it is full, the oldest automatic memories are removed first. Pinned facts
+are never removed. At 80%, the app shows: "{name}'s memory is 80% full
+({used} of {limit}). The limit is 2 GB or 100,000 memories, whichever comes
+first. When it is full, the oldest automatic memories are removed first.
+Pinned facts are never removed." The app also says: "The more {name}
+remembers, the harder it is to find older details; pinned facts are always in
+front of it."
+
+**RAM.** Plan for about 102 to 104 MiB more memory per agent at 100,000
+memories (measured 2026-10-11 in a standalone process on an x86_64 laptop). A
+small store uses less.
+
+**The search model.** The bridge downloads its search model from
+downloads.securecoms.ai the first time the owner messages the agent in their
+private chat with memory on, if the model files are not already on the
+machine. On a machine that must make no such connection, set
+`memory.model_source` to `import_only` in the credential file and copy the
+model bundle in with `agent-bridge models import <dir>`. Without the model,
+the agent finds memories by keyword only. On Windows it finds memories by
+keyword only in this release.
+
+If you embed the bridge as a library (`new BridgeAgent(cfg, deps)`), pass
+`hostMachine: true`. Without it, no model is downloaded or loaded, no call
+heartbeat is written, and the agent finds memories by keyword only. The
+`agent-bridge` command passes it for you.
 
 **Compatibility.**
 
-- Install `@securecoms/agent-runtime` 0.10.0 together with the bridge and
-  restart both (`launchctl bootout` then `bootstrap`, never `kickstart`). The
-  bridge moves legacy owner-DM facts into notes, and reports
-  `memory_notes: true`, only after a runtime whose hello declares
-  `memory_notes` has connected in that bridge process. A 0.9.x runtime's
-  hello does not, so a 0.27 bridge with a 0.9.x runtime keeps today's facts
-  and recall, but it is not a supported pairing.
+- Install `@securecoms/agent-runtime` 0.12.0 together with the bridge and
+  restart both (`launchctl bootout` then `bootstrap`, never `kickstart`). A
+  runtime whose hello does not declare `memory_unified` (0.11.0 or older) gets
+  no memories. That is not a supported pairing.
 - Harness daemons (Hermes, OpenClaw) must name `memory.provider` in their
-  credential file. A daemon whose file omits it is treated as `securecoms`;
-  its harness socket still never receives notes and never turns on the import
-  or the report, so naming the provider is defence in depth. A global
-  `npm install -g --prefix ~/.local` reaches every daemon whose plist points
-  at the global `dist/bin.js`, at its next restart; check each credential file
-  (`jq .memory.provider <credential-file>`) before installing.
-- A `/v1/ws` consumer that sends no hello waits about 2 seconds for its first
-  delivery.
-- Notes are off in a freshly started bridge until a runtime-config refetch
-  succeeds. A bridge restarted while the backend is unreachable serves no
-  notes and accepts no writes until the backend answers.
+  credential file. A daemon whose file omits it is treated as `securecoms`:
+  its bridge saves owner private-chat memories on disk, although its harness
+  socket never receives them. A global `npm install -g --prefix ~/.local`
+  reaches every daemon whose plist points at the global `dist/bin.js`, at its
+  next restart. Check each credential file
+  (`jq .memory.provider <credential-file>`) before you install.
+- Memory is off in a freshly started bridge until a runtime-config refetch
+  succeeds. A bridge restarted while the backend is unreachable saves and
+  recalls nothing until the backend answers.
+
+**Old notes and semantic memory.** The bridge copies a private chat's old
+memory into unified memory in the background, after the owner's first typed
+message in that chat on 0.29.0:
+
+- 0.27 notes become pinned facts. The 200-fact limit does not apply to them.
+- 0.28 semantic memory rows become automatic memories. Their search vectors
+  are kept.
+- The chat's stored history becomes reference memories.
+- A message forgotten in 0.28 is not copied. Text that looks like a password
+  or a key is not copied. Old facts, and the history of rooms and of other
+  people's private chats, are not copied.
+
+The old tables stay in this release, so a rollback works. Clear all and
+"forget that" also delete the matching old rows.
+
+**Off switches.** There are four. Use the narrowest that fits.
+
+- Agent memory off in the agent settings. The agent saves nothing new and
+  recalls nothing. It still sees the recent messages of the chat. Turning
+  memory off does not delete memories. Use Clear all for that.
+- `memory.enabled: false` in the credential file, then a daemon restart. The
+  same effect, and the backend cannot turn it back on. Any value other than
+  `true` turns memory off.
+- `memory.provider: "none"` in the credential file, then a daemon restart.
+  This turns memory off, and it also drops the recent history.
+- `SECURECOMS_OWNER_DM_DEFAULT_GRANTS=off` in the bridge service environment.
+  This turns memory off, and it also drops the owner private-chat tools.
+
+`SECURECOMS_TOOL_DENY=memory_note` (runtime environment) removes only the pin
+and forget tool. The agent still saves and recalls memories.
 
 **Known limitations.**
 
-- Text the owner pastes counts as the owner's own words, up to the
-  600-unit short-message bound.
-- A quote can drop a condition or a negation ("Never cc X" can be saved as
-  "cc X"). Ask the agent what it saved.
-- Short notes in CJK or Thai (fewer than 2 space-separated tokens) are
-  refused.
-- UUIDs and long letter-and-digit tokens are refused as possible secrets.
+- A pin can reorder the owner's words or leave one out, including a negation
+  ("don't pay Bob, pay Alice" can be pinned as "pay Bob"). Read the
+  `Pinned:` line, and say "forget that" if it is wrong.
+- Clear all deletes memories. It does not delete chat history.
 - Forget and clear are logical deletes: sealed bytes can stay in free
-  database pages until they are overwritten, and they still open under the
-  device key.
-- "Clear all notes" does not delete chat history or legacy facts. Legacy facts
-  that did not fit before can become notes after a clear.
-- The voice fast path still sends the last 10 DM messages through the
-  backend proxy.
-
-**Off switches.** There are three. Use the narrowest that fits.
-
-- `memory.provider: "none"` in the credential file, then a daemon restart.
-  This turns notes off, and it also drops the recent history.
-- `SECURECOMS_OWNER_DM_DEFAULT_GRANTS=off` in the bridge service environment.
-  This also drops the owner-DM tools, not only `memory_note`.
-- `SECURECOMS_TOOL_DENY=memory_note` removes only the note tool.
-
-**Log events.** All are content-free: counts and classes only, never note text.
-`memory.note_written` (`op`, `notes_count`, `doc_chars`),
-`memory.note_refused` (`reason_class`), `memory.notes_cache_miss`,
-`memory.note_open_failed`, `memory.import_partial` (`remaining`),
-`memory.config_unrecognized`, `memory.clear_generation_regressed`,
-`memory.clear_failed`, `memory.applied_generation_out_of_range`,
-`memory.notes_fill_failed`, `memory.import_failed`,
-`memory.note_write_failed` (error class only), and `ws.hello_timeout` (no
-fields: a `/v1/ws` socket sent no hello and delivery opened after the wait).
+  database pages or the WAL until they are overwritten, and they still open
+  under the device key.
+- The model provider sees the memories that the bridge delivers.
+
+**Log events.** All are content-free: counts and classes only, never memory
+text. `memory.item_written` (`source`, `chunks`), `memory.item_skipped`
+(`reason_class`), `memory.pin_written`, `memory.item_forgotten`,
+`memory.note_refused` (`reason_class`), `memory.migration_ran` (`notes`,
+`recall`, `history`, `skipped`, `excluded`, `aborted`, `unreadable`),
+`memory.owner_scope_purged` (`count`), `memory.unified_off`
+(`reason_class`: `off`, `unrecognized`, `local` or `clear_pending`),
+`memory.ranking_worker_exited` (`inFlight`), and these failure events with the
+error class only: `memory.unified_clear_failed`,
+`memory.unified_switch_failed`, `memory.unified_report_failed`,
+`memory.unified_prepare_failed`, `memory.unified_reply_failed`,
+`memory.unified_boot_reconcile_failed`, `memory.migration_failed`,
+`memory.owner_scope_sweep_failed`, `memory.note_write_failed`,
+`memory.pinned_line_failed`, `memory.forgot_line_failed`,
+`memory.evict_failed`, `memory.reembed_failed`, `memory.model_upkeep_failed`,
+`memory.ranking_notify_failed` and `memory.ranking_worker_spawn_failed`.
+
+**`/healthz` and the machine report.** `/healthz` adds `memory_hot_bytes`,
+`memory_deadline_misses`, `memory_reads`, `memory_reads_discarded` and `pid`.
+The machine report adds `memory_unified_enabled`, `memory_size_bytes`,
+`memory_item_count`, `memory_db_bytes` and `memory_near_full`. All are
+numbers or booleans.
 
 **Upgrade order.** Upgrade and restart the bridge and the runtime together.
 First check `memory.provider` in the credential file of every daemon that a
 global install reaches (`jq .memory.provider <credential-file>`).
 
-**Rollback.** A 0.26.x bridge leaves the notes sealed on disk and reads
-neither the notes nor the legacy facts already moved into them, until it is
-upgraded again; the same holds for a 0.9.x runtime. Roll back the runtime and
-the bridge together, and restart both: the bridge decides once per process
-that a notes-reading runtime is present.
-
-## Semantic memory: model download and retention
-
-<!-- [COPY, NEW] the three paragraphs below, the log-line paragraph included (7b Task 19, spec §19 LOW; first sentence corrected in the 7b-2 final-review fix round). Gate: Eric sign-off before npm publish (release PR). -->
-
-Semantic memory downloads its model from downloads.securecoms.ai when the owner first messages the agent in their private chat after semantic memory is turned on, not when the setting is saved. On a machine that must make no such connection, set `memory.model_source` to `import_only` in the credential file and copy the model bundle in with `agent-bridge models import <dir>`.
-
-If you change the memory provider or turn off owner-DM defaults, semantic memory rows stay on the machine until their retention ends, but they are never used.
-
-The bridge logs `memory.model_download_enabled` (no fields) once per process
-when semantic memory is turned on with `model_source` `download`.
-
-<!-- [COPY, NEW] (7b Task 19 fix round 2). Gate: Eric sign-off before npm publish (release PR). -->
-
-If you embed the bridge as a library (`new BridgeAgent(cfg, deps)`), semantic recall stays inert unless you pass `hostMachine: true`: no model is downloaded or loaded, and no call heartbeat is written. The `agent-bridge` command passes it for you.
+**Rollback.** Roll back the bridge and the runtime together, to 0.28.2 and
+0.11.0, and restart both. A 0.28.2 bridge opens the database, ignores the
+unified tables, and works on the old notes, semantic memory rows and history
+that 0.29.0 kept. It does not see what 0.29.0 saved, pinned facts included. It
+never removes or clears the unified tables, so the size limit does not apply
+to them until you upgrade again. When 0.29.0 starts again, before it serves
+anything, it removes copied pins whose old note was deleted during the
+rollback, removes copied memories whose message was forgotten, and applies a
+Clear all done during the rollback. Old rows added during the rollback are
+copied after the owner's next typed message.
 
 ---
 
+## Release notes: 0.29.0
+
+<!-- [COPY, NEW] Approved by Eric 2026-10-11 (plan Task 37). -->
+
+0.29.0 turns on unified memory in the owner's private chat. Install it
+together with `@securecoms/agent-runtime` 0.12.0 and restart both. See
+"Unified memory (0.29.0)" above.
+
+- **One memory.** Typed messages, spoken call turns, the agent's replies and
+  pinned facts are kept in one sealed memory. Rooms and other people's private
+  chats are not remembered in this release.
+- **Old memory moves.** 0.27 notes and 0.28 semantic memory rows are copied in
+  after the owner's next typed message. The old tables stay for one release.
+- **Limits.** 2 GB or 100,000 memories, whichever comes first. Pinned facts are
+  never removed.
+- **RAM.** About 102 to 104 MiB more per agent at 100,000 memories
+  (measured in a standalone process, not yet inside a running bridge).
+- **Off switches.** A new credential key, `memory.enabled: false`, turns memory
+  off on the machine. `SECURECOMS_TOOL_DENY=memory_note` now removes only the
+  pin and forget tool; automatic memory continues.
+- **Skills in the owner's private chat.** With runtime 0.12.0, the memory
+  tool gate refuses every skill on the owner's private-chat turns. Only
+  `current_time`, `echo`, `memory_note`, and `web_search`, `fetch_url`,
+  `http_request` (GET) and `sql_query` with arguments that pass the gate, run
+  there. Skills in rooms are not changed.
+- **`/healthz`.** New `memory_hot_bytes`, `memory_deadline_misses`,
+  `memory_reads`, `memory_reads_discarded` and `pid`.
+
 ## Release notes: 0.28.2
 
 <!-- [COPY, NEW] this section. Approved by Eric 2026-10-09 ("approve 0.28.2 copy"). -->
@@ -816,7 +913,7 @@ unchanged.
 
 ## Release notes: 0.28.1
 
-<!-- [COPY, NEW] this section. Gate: Eric sign-off before npm publish (release PR). -->
+<!-- [COPY, NEW] this section. Approved by Eric 2026-10-09. -->
 
 0.28.1 makes semantic memory recall more reliable. Install it in place of
 0.28.0 and restart the bridge. `@securecoms/agent-runtime` 0.11.0 is unchanged.
@@ -845,7 +942,7 @@ with `@securecoms/agent-runtime` 0.11.0 and restart both.
 - **`import_only`.** Set `memory.model_source` to `import_only` on a machine
   that must make no model download.
 - **`models import`.** `agent-bridge models import <dir>` copies a model bundle
-  in for `import_only` machines. <!-- [COPY, NEW] the one-line CLI confirmation "imported <names>" printed by `models import` (src/bin.ts). Gate: Eric sign-off before npm publish (release PR). -->
+  in for `import_only` machines. <!-- [COPY, NEW] the one-line CLI confirmation "imported <names>" printed by `models import` (src/bin.ts). Approved by Eric 2026-10-09. -->
 
 ## Test commands