parallelclaw 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,204 @@
+# Changelog
+
+Notable changes to parallelclaw (formerly memex-mvp). Older history lives in the git log.
+
+## 1.0.0 — rebrand: memex → ParallelClaw
+
+The product is renamed **ParallelClaw** and repositioned from "AI memory" to a
+**personal AI ops layer**: shared verbatim memory is the foundation, and a
+coordination layer — any of your agents delegates a task to any other, across
+tools and machines — is the direction. No users yet = the cheapest moment to fix
+the name before building coordination under it.
+
+This release renames the **surface** only; the **plumbing stays** as back-compat
+aliases, so the live sync mesh and every existing install keep working untouched.
+
+### Changed
+- **npm package `memex-mvp` → `parallelclaw`.** New bins `parallelclaw` + `pclaw`
+  (aliases of `server.js` — the query CLI / MCP server). `--version` now prints
+  the package name. Install is now `npm install -g parallelclaw`.
+- **READMEs / landing / HELP / SYNC / skills / installers** rebranded to
+  ParallelClaw, plus a coordination **vision section** on the landing and READMEs
+  (no vaporware: memory ships today; the turnkey delegation loop is rolling out).
+
+### Kept as-is (back-compat — must NOT break the live mesh)
+- Legacy bins `memex` / `memex-sync` / `memex-ingest` / `memex-bot` (docs still
+  use `memex …` / `memex-sync …` verbatim).
+- Data dir `~/.memex`, DB `memex.db`, env vars `MEMEX_*`.
+- launchd/systemd labels `com.parallelclaw.memex.*`.
+- MCP tool names `memex_*`.
+- GitHub repo path `parallelclaw/memex-mvp` and `git clone` dirs (repo rename
+  pending — a separate, out-of-band step; URLs unchanged for now).
+
+## 0.14.1 — patch: schema migration at sync-server boot
+
+Upgrading a hub by `npm install -g` alone (no daemon/MCP boot in between) and
+restarting the sync-server crash-looped it: the pull handler prepares a SELECT
+over the new `origin` column at startup, against a not-yet-migrated DB.
+`startSyncServer` now runs `initializeDb` before opening its handle. Found
+live during the 0.14.0 rollout.
+
+## 0.14.0 — provenance: know which machine captured every row
+
+In a synced mesh, all nodes' captures share the same `source` labels — two
+OpenClaw instances both write `source='openclaw'`, and when they bridge the
+same Telegram account they even interleave into ONE conversation. Two agents
+in a row misread their own synced DB because of this (one invented a
+nonexistent `source='vps1'` to look for — telling). v0.14 stamps every row
+with the node that captured it.
+
+### Added
+- **`origin` column on messages** — stamped at capture time on every local
+  write path (capture daemon, MCP imports, Telegram import, store_document,
+  sync self-test, OpenClaw plugin). Value resolution: `MEMEX_ORIGIN` env →
+  `origin` in `~/.memex/config.json` → sanitised short hostname, which is
+  then **persisted** so a later hostname change doesn't fork the node's
+  identity. Rename your node by editing `origin` in config.json.
+- **Wire carries provenance** — sync pull/push move `origin` verbatim in both
+  directions; a synced row keeps the origin of the node that captured it,
+  never the receiver's. Old peers interoperate (unknown field ignored;
+  their rows arrive as NULL = "pre-provenance era").
+- **`memex_search(origin: "vps1")`** — filter recall by capture node.
+- **`memex_get_conversation`** tags each line `[@origin]` when a conversation
+  interleaves rows from more than one node (the merged-Telegram-chat case);
+  single-origin chats stay untagged. JSON format always includes `origin`.
+- **`memex_overview`** shows a per-origin breakdown when the corpus is
+  multi-node.
+
+### Notes
+- No blind backfill: a node cannot tell its own pre-v0.14 rows from peer rows
+  that synced in before provenance existed, and fabricating provenance is
+  worse than NULL. Re-imports of local source files DO backfill origin via
+  the conflict branch (`COALESCE(existing, incoming)` — never overwrites).
+- The OpenClaw plugin (`plugins/memex-openclaw`) ships separately from the
+  npm package — update it on agent nodes to start stamping there.
+
+## 0.13.0 — `sync-join`: cross-device memory in two copy-paste steps
+
+Multi-device sync goes from "for operators" to "for lazy users". Laptop with
+Claude/Cursor + a server with an agent: the agent runs three commands and
+hands you a `memex-join:` token; you paste **one command** on the laptop.
+Dogfooded end-to-end by migrating the maintainer's own live mesh — every step
+below shipped only after surviving that.
+
+### Added
+- **`memex-sync sync-join <memex-join:...>`** — one-command spoke setup:
+  token validation → SSH probe (prints your pubkey + exact instructions if
+  access is missing) → durable forward tunnel (launchd KeepAlive / systemd
+  Restart=always; `ExitOnForwardFailure`, `ServerAlive 30×3`, explicit IPv4
+  loopback) → pinned-cert health check → remote registration → first sync →
+  15-min auto-sync schedule → hourly watchdog → **marker self-test** that
+  proves a note round-trips before declaring success (`✓ end-to-end verified:
+  … 3.4s` on the live pair). Flags: `--alias`, `--local-port`, `--every`,
+  `--no-watchdog`, `--no-selftest`.
+- **`memex-sync sync-server invite --join [--ssh-target u@h]`** — hub-side
+  join-token emission (`memex-join:` = pair blob + `ssh_target`, host pinned
+  to 127.0.0.1, TTL 30m). The server stays loopback-only; nothing is ever
+  exposed publicly — all traffic rides inside SSH on port 22.
+- **`memex-sync sync-watchdog`** — read-only hourly health pass (installed by
+  join): remotes' `last_sync_at` freshness + tunnel unit state; on silence
+  writes `~/.memex/sync-alert.txt` + desktop notification. The "tunnel died
+  silently for 6 days" failure mode, productized away.
+- **`sync-status`** now reports the tunnel keeper (route, self-healing state)
+  and watchdog alongside server/schedule/remotes.
+
+### Changed
+- **No env var after joining** — a successful `sync-join` persists
+  `sync.enabled: true`; every sync command then works in any shell without
+  `MEMEX_SYNC_EXPERIMENTAL=1`.
+- **Replication is resumable** — cursors persist after every clean pull page
+  and push batch, so an interrupted first sync (network reset, sleep, Ctrl-C)
+  resumes instead of restarting from zero; transient network errors
+  (ECONNRESET/EPIPE/ETIMEDOUT/ECONNREFUSED) retry in place with backoff tuned
+  to the tunnel's ~15s self-heal.
+- **Re-joining a known hub keeps cursors** — if the token's cert fingerprint
+  matches the existing remote's, sync-join preserves cursor state instead of
+  forcing a full re-replication of an already-converged pair.
+- **Docs lead with the lazy flow** — landing page, README (EN/RU), SYNC.md
+  quickstart, HELP.md section, MULTI_MACHINE.md legacy patterns marked
+  deprecated.
+
+### Fixed
+- Tunnel-keeper script generation emitted a broken line continuation (`\ \`)
+  when no SSH identity file was configured — ssh received a stray empty
+  argument and the tunnel flapped forever. Regression-tested, including
+  backslash hygiene of every continuation line.
+
+## 0.12.0 — agent retrieval: reach any part of memory
+
+Sharper recall for agents querying memex — especially across long sessions and
+narrow time windows. Backward-compatible: every new parameter is optional and
+defaults to the previous behaviour.
+
+### Added
+- **`memex_get_conversation` paging** — new `offset` and `order` (`asc`|`desc`)
+  parameters, plus a `total` count in the output. A long session (e.g. 3000
+  messages) can now return its **freshest** tail (`order:"desc"`) or be paged
+  end-to-end — previously only the first ~N (oldest) were reachable. Fixes a real
+  gap found live: an agent could not show the June messages of a 2900-message
+  Claude Code session.
+- **`memex_search` date-range filter** — `since_ts` / `until_ts` (Unix seconds,
+  inclusive) restrict results to a window ("what did we discuss about X in June").
+  A true filter, distinct from `sort` (orders only) and `half_life_days` (boosts
+  only). Numeric bounds naturally exclude undated rows.
+- **`memex_search` within-conversation scope** — `conversation_id` confines a
+  keyword search to ONE session (exact id, unlike the fuzzy `chat` title match).
+  Pair it with `memex_get_conversation` paging to locate, then read around a hit
+  in a huge session.
+- **Retrieval recipes** baked into the tool descriptions and `HELP.md` (new
+  "Рецепты поиска для агентов" table) so agents discover these paths without
+  guessing — date window, within-session search, freshest-first, page-a-giant.
+
+### Fixed
+- **`memex_get_conversation` no longer hides the tail of long conversations** —
+  the handler always sorted `ts ASC LIMIT N` with no offset, so the newest
+  messages of any session past the limit were unreachable.
+- **`test/sync/mcp-invite.test.js` is now hermetic** — the liveness-warning
+  assertion used a hard-coded port and failed on hosts that actually run a
+  sync-server on 8766; it now probes a guaranteed-closed port.
+
+## 0.11.11 — experimental multi-device sync
+
+First cut of **local-first, multi-device sync** — converge two machines'
+`memex.db` over the network with no cloud relay. Gated behind
+`MEMEX_SYNC_EXPERIMENTAL=1`; the wire protocol may change before it graduates
+to stable. Full guide + spec in [SYNC.md](SYNC.md).
+
+### Added
+- **Sync engine** — HTTP push/pull + per-peer cursors. Conflict-free via the
+  existing `UNIQUE(source, conversation_id, msg_id)` constraint (verbatim memory
+  is append-only — nothing to merge). TLS with self-signed cert + **fingerprint
+  pinning**, 256-bit bearer auth.
+- **CLI** (`memex-sync sync-*`):
+  - `sync-server start | install | uninstall | status` — run the hub, optionally
+    as a durable systemd-user / LaunchAgent service that survives reboot.
+  - `sync-server invite [--host H] [--port N] [--ttl 30]` — print a one-paste
+    `memex-pair:` token (bundles host + port + cert fingerprint + bearer, with TTL).
+  - `sync-pair <blob> [--alias vps]` — register a remote from a pair token.
+  - `sync-add <alias> <url> <bearer> (--cert-fp F | --insecure)` — explicit form.
+  - `sync-run <alias> | --all` — one bidirectional sync.
+  - `sync-schedule install [--every 15m] | uninstall | status` — hands-off
+    auto-sync on a timer.
+  - `sync-list / sync-remove / sync-status`.
+- **`memex_sync_invite` MCP tool** — lets an agent emit a pairing token from a
+  plain-language request ("set up sync with my Mac"). Surfaced only when
+  `MEMEX_SYNC_EXPERIMENTAL=1` is set in the MCP server's environment.
+
+### Reliability
+- **Adaptive push batching** — pre-flights payload size and shrinks before the
+  2 MB body cap; backstops 413 / EPIPE by halving and retrying.
+- **No silent row loss** — pulled rows are applied with retry; on the FTS5
+  "database disk image is malformed" error the index is rebuilt once and the
+  batch retried; if rows still won't apply, sync aborts **without advancing the
+  cursor** (loud failure over silent loss). Skips are counted and surfaced.
+- **busy_timeout** on the sync connection to ride out the capture daemon's
+  concurrent writes.
+
+### Verified live
+- Bidirectional Mac ↔ VPS sync over the public internet (32k+ rows each side,
+  cert-pinned), durable-server restart with credentials preserved, hands-off
+  auto-sync of a fresh conversation within one interval, and the full
+  agent-chat-phrase → pair-token → sync wow-flow.
+
+### Dependencies
+- Added `selfsigned` (self-signed TLS cert generation for the sync server).