memorix 1.8.9 → 1.9.0

package/docs/CONFIGURATION.md

@@ -370,6 +370,52 @@ Common keys:
 - `dashboard_port = 3210` — default port for `memorix dashboard` when
   `--port` is not given.
 
+### Optional store sync
+
+Store sync is disabled unless `MEMORIX_SYNC_PROVIDER` is explicitly set. It
+replicates approved project-visible observation events, never the live SQLite
+file or its `-wal` / `-shm` companions. The local SQLite store remains the
+canonical read/write store.
+
+```text
+MEMORIX_SYNC_PROVIDER=fs|github|s3|postgres
+```
+
+The filesystem relay needs `MEMORIX_SYNC_FS_ROOT`. The GitHub relay needs a
+private relay repository and token:
+
+```text
+MEMORIX_SYNC_GITHUB_REPO=owner/repository
+MEMORIX_SYNC_GITHUB_TOKEN=...
+MEMORIX_SYNC_GITHUB_BRANCH=memorix-sync        # optional
+```
+
+For S3-compatible storage, set the usual bucket/endpoint/credentials/region
+variables and optionally put all Memorix objects below a shared-bucket prefix:
+
+```text
+MEMORIX_SYNC_S3_BUCKET=...
+MEMORIX_SYNC_S3_ENDPOINT=...
+MEMORIX_SYNC_S3_ACCESS_KEY_ID=...
+MEMORIX_SYNC_S3_SECRET_ACCESS_KEY=...
+MEMORIX_SYNC_S3_REGION=auto
+MEMORIX_SYNC_S3_PREFIX=memorix       # optional, relative key prefix
+```
+
+S3-compatible and Postgres details are documented in the multi-device sync
+[plan and acceptance contract](MULTI-DEVICE-SYNC-RESEARCH.md). Credentials are
+read from the process environment and are never written to project config or
+sync event bodies. A copied data directory must be rotated before it can
+publish:
+
+```bash
+memorix sync store device rotate
+```
+
+Use `memorix sync store status --json` first. It reports the current project
+namespace, eligible/excluded records, pending outbox work, and conflicts without
+creating a remote branch or uploading anything.
+
 ### Reserved sections (parsed, not yet enforced)
 
 These sections exist so future releases do not need a config format change.

package/docs/DEVELOPMENT.md

@@ -13,8 +13,8 @@ Memorix is a TypeScript project built around:
 
 ## Current Development Baseline
 
-The current release work targets the **1.8.6 release line** and package metadata
-is kept at `1.8.6` for this release commit.
+The current release line is **1.9.0** and package metadata is kept synchronized
+with the root package and MCP Registry manifest.
 
 Contributors should assume the following areas are part of the current release line:
 

package/docs/MULTI-DEVICE-SYNC-RESEARCH.md

@@ -0,0 +1,344 @@
+# Multi-Device Store Sync — Plan and Acceptance Contract
+
+> Status: released in 1.9.0. Background sync, broader table replication, and
+> encrypted snapshots remain future work.
+> Scope: keep the existing local-first SQLite runtime; add an optional,
+> provider-agnostic replication path so one user can keep the same memory
+> across several machines.
+>
+> Contribution credit: the design, initial implementation, and the
+> object-store/Postgres follow-up came from Ravi Tharuma's PR #277. The local
+> hardening branch keeps those commits in its merge history and adapts them to
+> the current v3 contract.
+> Prior art in this repo: `docs/CLOUD_SYNC_AND_MULTI_AGENT_RESEARCH.md`
+> already sketched a "local SQLite + background cloud sync" hybrid but did not
+> specify or build it. This document turns that sketch into a concrete,
+> reviewable contract.
+
+## Decision Summary
+
+The sync layer must replicate **auditable memory events**, never a live SQLite
+file. GitHub can be a low-cost relay for immutable JSONL batches, but GitHub
+LFS is not a database merge engine and is not the production default. The
+runtime keeps SQLite local and treats each remote as an interchangeable event
+transport.
+
+The first supported contract is deliberately narrow:
+
+- **Scope:** the current Git project by default. A remote namespace includes the
+  canonical project ID; one project cannot pull another project's events by
+  accident.
+- **Eligibility:** project-visible, non-ephemeral, qualified/legacy durable
+  observations only. Personal, agent-targeted, candidate, and ephemeral records
+  are excluded unless a future explicit export policy opts them in.
+- **Identity:** every sync key includes the project ID. Unkeyed rows also carry
+  origin device and origin ID, so global store IDs can never cross projects.
+- **Transport:** immutable per-device event batches, local cursors, checksums,
+  bounded pulls, and idempotent replay. Remote cursors are not authoritative.
+- **Conflict:** logical version order decides the current visible row, while a
+  losing concurrent version remains available as conflict/audit evidence rather
+  than disappearing silently.
+- **Device safety:** a copied data directory is detected as a clone and must
+  rotate its device identity before it can publish new events.
+- **User experience:** manual `status`, `push`, `pull`, and `repair` first;
+  background sync is a later opt-in once retention and recovery gates pass.
+
+## Implementation Phases
+
+| Phase | Deliverable | Gate |
+| --- | --- | --- |
+| P0 | Plan, scope, privacy and event contract | docs map updated; no live SQLite sync path |
+| P1 | Project-scoped local journal and safe eligibility filter | private/candidate/other-project fixtures never leave the scope |
+| P2 | Deterministic merge, tombstones, conflicts, clone detection | permutation, delete, replay, clone and conflict tests pass |
+| P3 | Filesystem and GitHub JSONL relays | two real data directories reconcile without DB/WAL files |
+| P4 | Bounded S3/Postgres pulls and remote namespace isolation | paged pull, malformed input, retry and large-log tests pass |
+| P5 | Explicit remote compaction and CLI repair | cleanup is preview-first and only deletes acknowledged events |
+| P6 | Cross-platform smoke and release review | Windows/macOS/Linux checks, docs, package smoke, contributor credit |
+
+## GitHub Relay Contract
+
+The GitHub adapter uses a private repository as a versioned transport, not as
+the canonical database:
+
+```text
+events/<project-hash>/<device-id>/<sequence>.jsonl
+snapshots/<project-hash>/<snapshot-id>.json.zst
+```
+
+Event files are immutable and device-owned. A device never edits another
+device's file and never commits `memorix.db`, `memorix.db-wal`, or
+`memorix.db-shm`. Each event contains a schema version, project namespace,
+device ID, sequence, entity key, operation, logical version, visibility
+decision, content hash, and payload. At-rest encryption is a future transport
+option; this first slice does not pretend to provide it. Credentials never
+enter project files or event bodies.
+
+Snapshots are normalized, replayable memory state, not a copy of an open
+SQLite file. SQLite's Online Backup API may be used for a local backup, but a
+backup is not a merge input.
+
+## Acceptance Checklist
+
+- [x] `memorix sync store status --json` reports scope, eligible/skipped counts,
+      remote namespace, cursor, pending batches, and conflicts without sending data.
+- [x] `push` and `pull` are idempotent and resumable after interruption.
+- [x] Two stores with independent local integer IDs converge to the same visible
+      records while retaining local IDs locally.
+- [x] A stale upsert cannot revive a newer delete.
+- [x] A concurrent same-key edit keeps both the winner and a reviewable losing
+      version/audit record.
+- [x] Personal, agent-targeted, candidate, ephemeral, and other-project rows
+      are excluded by default.
+- [x] Copying a data directory produces a clear device-clone error and a
+      documented `device rotate` recovery path.
+- [x] GitHub relay protocol smoke proves only JSONL/snapshot artifacts are uploaded;
+      no SQLite database or WAL file is present.
+- [x] Pulls are bounded and keyset-paged; remote logs have an explicit
+      acknowledged retention/compaction path.
+- [x] Malformed, foreign-project, unsupported-version, and hash-mismatch input
+      fails closed without mutating local memory.
+- [x] Local-only users see no behavior or dependency change when sync is unset.
+
+---
+
+## 1. Problem
+
+A single user commonly runs Memorix on more than one machine — for example a
+workstation, a home machine, and a portable laptop. Today each machine keeps
+its own independent store at `~/.memorix/data` (`MEMORIX_DATA_DIR`). There is
+no supported way to keep those stores current with each other, so the memory a
+user sees depends on which machine they happen to open.
+
+Two deployment shapes are sometimes proposed to solve this. Both have real
+costs:
+
+1. **Run one central Memorix service and point every machine at it over HTTP.**
+   `serve-http` already supports this (see `docs/DOCKER.md`). It gives a single
+   shared store, but it trades away the properties that make Memorix useful on
+   a workstation:
+   - **Project-scoped features degrade.** Git-root detection, project binding,
+     project `memorix.toml`/`.env`, and Git Memory require the service to see
+     the repository at the path the client reports. A central host usually
+     cannot see a laptop's working copy, so project-scoped semantics break
+     while only global/shared memory keeps working. `docs/DOCKER.md` documents
+     this as a real runtime limitation.
+   - **Latency on the hot path.** Every context call, session start, and hook
+     becomes a network round trip instead of a local SQLite read.
+   - **Offline stops working.** A portable machine with no connectivity has no
+     memory at all.
+   - **Single-writer contention.** One SQLite file serving several machines
+     serializes writes and invites `SQLITE_BUSY`.
+
+2. **Replace SQLite with a central client/server database (e.g. Postgres).**
+   This contradicts the stated local-first product boundary in
+   `docs/KNOWN_ISSUES_AND_ROADMAP.md`, and would require rewriting the
+   synchronous `better-sqlite3` store layer (`src/store/*.ts`) onto an async
+   client with a different SQL dialect and a different vector story. It removes
+   offline use and adds an always-on infrastructure dependency for what is
+   meant to be a local tool.
+
+Neither shape preserves local-first. The gap is a **third shape**: keep the
+store local on every machine, and add an **optional replication layer** that
+keeps those local stores consistent through an interchangeable remote.
+
+---
+
+## 2. Goals and non-goals
+
+### Goals
+
+- Preserve local-first: reads and writes stay on the local SQLite store; sync
+  is asynchronous and off the hot path.
+- Keep working offline; reconcile on the next successful sync.
+- Be **provider-agnostic**: the remote is an interface, not a specific vendor.
+  A local filesystem/rsync target, an object store (S3-compatible), or a small
+  edge datastore must all be valid backends behind the same contract.
+- Be **opt-in and safe**: sync is disabled by default; enabling it never
+  changes local behavior for users who do not use it.
+- Deterministic, explainable merge: a user can inspect what would change before
+  it is applied, consistent with the preview-first maintenance model.
+
+### Non-goals
+
+- No real-time multi-writer coordination or distributed locking. That is the
+  `team`/orchestration surface, not this.
+- No requirement to run a central Memorix service.
+- No replacement of the SQLite runtime or the retrieval/embedding model.
+- No claim of conflict-free collaboration between different users; this targets
+  one user's several machines. Multi-user sharing is a separate concern.
+
+---
+
+## 3. Why the current schema already supports this
+
+The canonical store carries most of what a convergent last-writer-wins (LWW)
+merge needs, and the small remainder lives in additive side tables so the
+`observations` schema never changes:
+
+- **Stable cross-device identity.** The integer `observations.id` is a
+  *replica-local* counter (`meta.next_id`) — two machines can mint the same id
+  for unrelated rows — so it cannot be the merge key. Sync instead derives a
+  stable `syncKey`: `t:<projectId>:<topicKey>` for topic-keyed observations
+  (naturally shared across devices) and `u:<originDevice>:<originId>` for
+  unkeyed ones, minted once and recorded in `sync_row_state`. Each replica maps
+  a `syncKey` to its own local id on import, so id collisions are impossible.
+- **Convergent versioning.** Merge uses a per-row logical clock
+  `(revision, writer)` — a Lamport counter advanced from the last observed
+  revision, tiebroken by the originating device id — persisted verbatim in
+  `sync_row_state`. This is a strict total order, so replaying batches in any
+  delivery order reaches the same state. `writeGeneration`/`updatedAt` remain a
+  local storage watermark and are deliberately *not* used as the comparator
+  (they are not comparable across replicas).
+- **Durable tombstones.** Deletes are versioned states retained in
+  `sync_row_state`, so a stale upsert pulled later cannot resurrect a row a
+  newer delete removed.
+- **Provenance.** `source`, `sourceDetail`, `createdByAgentId`, `projectId`,
+  and `sessionId` let a merge attribute and scope rows.
+
+A first version therefore replicates at the **observation row** granularity
+with no migration of existing data: identity, version, and tombstone state all
+live in the additive `sync_row_state` / `sync_meta` tables.
+
+---
+
+## 4. Proposed architecture
+
+### 4.1 Two layers
+
+1. **A change journal (local).** A small append-only log of committed mutations
+   keyed by table + row id + logical version. This can be derived from existing
+   columns for observations in v1, and generalized to other tables later. The
+   journal is what gets shipped, so sync never has to diff the whole 900 MB
+   database.
+2. **A replication transport (remote).** A narrow interface that can `push`
+   local journal segments and `pull` remote ones. The store never talks to a
+   vendor directly; it talks to this interface.
+
+### 4.2 Transport interface (provider-agnostic)
+
+```ts
+// Final interface (src/sync/types.ts). The cursor maps deviceId -> last applied
+// sequence locally; the page token is an opaque keyset continuation for one
+// bounded pull.
+interface SyncRemote {
+  readonly kind: string;                 // "fs" | "github" | "s3" | "postgres"
+  readonly namespace: string;
+  init(options?: { create?: boolean }): Promise<void>;
+  push(batch: ChangeBatch): Promise<void>;            // idempotent by (deviceId, sequence)
+  pull(since: Record<string, number>, limit: number, pageToken?: string): Promise<SyncPullPage>;
+  compact(through: Record<string, number>, options?: { dryRun?: boolean }): Promise<SyncCompactReport>;
+  close(): Promise<void>;
+}
+```
+
+Concrete adapters implement `SyncRemote` only:
+
+- **`fs`/`rsync`** — a directory the user already syncs by other means; zero
+  new infrastructure, good for a first, fully local test.
+- **`github`** — an optional private-repository JSONL relay; it is convenient
+  for a small personal store, not a database.
+- **`s3`** — any S3-compatible object store; batches are immutable objects
+  under a project path and optional user prefix.
+- **`postgres`** — a batch-log hub for users who already operate Postgres.
+
+The point is that no adapter is privileged. Provider choice is configuration,
+not code, mirroring how `[memory.llm]`, `[embedding]`, and rerank already
+select providers by config.
+
+### 4.3 Merge strategy
+
+- **Row-level last-writer-wins**, merged by the stable `syncKey` and versioned
+  by the per-row logical clock `(revision, writer)`. The comparison is a strict
+  total order, so the merge is convergent: any delivery/replay order of the
+  same batches yields the same final state.
+- **No lifecycle special-casing.** An earlier design ordered `status`
+  transitions in lifecycle rank; that made the merge order-dependent (applying
+  `active`@rev2 then `archived`@rev1 diverged from the reverse). Revision
+  ordering alone already prevents a stale `active` copy from overriding a newer
+  supersession/archival, so the guard was removed in favour of provable
+  convergence.
+- **Durable tombstones.** A delete is a versioned state kept in
+  `sync_row_state`, so a delete on machine A is never resurrected by machine B's
+  stale upsert — even when B pulls the old upsert after the delete.
+- **Preview-first:** `sync --dry` reports the exact set of inserts, updates,
+  supersessions, and tombstones that would apply, consistent with the existing
+  preview-first maintenance actions.
+
+### 4.4 Configuration surface (illustrative)
+
+```toml
+[sync]
+enabled = false          # opt-in; default off
+provider = "fs"          # fs | s3 | edge-kv | ...
+mode     = "manual"      # manual | interval
+# provider-specific settings live under a provider table, e.g. [sync.s3]
+# credentials come from the environment, never from this file
+```
+
+Credentials and endpoints are resolved from the environment (as LLM/embedding
+keys already are), never written into a config file that could be shared.
+
+### 4.5 CLI surface (illustrative)
+
+- `memorix sync push` / `memorix sync pull` / `memorix sync status`
+- `memorix sync --dry` for a preview before applying
+- Optional background interval sync gated behind `[sync].mode = "interval"`
+
+> Note: `memorix sync` today handles cross-agent **rules** synchronization
+> (`src/cli/commands/sync.ts`). Store replication must not collide with that
+> surface; it should live under a clearly separated subcommand namespace
+> (for example `memorix sync store ...`) or a new top-level verb, decided by
+> the maintainer.
+
+---
+
+## 5. Phasing
+
+1. **Phase 1 — journal + local relay, observations only.** Complete.
+   Two real SQLite data directories reconcile through a shared filesystem
+   relay, with project scope, privacy filtering, merge, delete, and clone
+   protection.
+2. **Phase 2 — remote relays + preview.** Complete as a contract and adapter
+   test slice. GitHub, S3-compatible, and Postgres transports are opt-in;
+   provider credentials and live service acceptance remain deployment work.
+3. **Phase 3 — snapshots and broader tables.** Future. The current release
+   does not replicate sessions, knowledge, CodeGraph, or encrypted snapshots.
+4. **Phase 4 — background sync.** Future. Manual status/push/pull remains the
+   deliberate first user experience until recovery, privacy, and lifecycle
+   telemetry are proven.
+
+Each phase is independently useful and independently reviewable.
+
+---
+
+## 6. Compatibility and safety
+
+- **Default off.** Users who never enable `[sync]` see no behavior change.
+- **No hot-path cost.** Sync runs asynchronously; local reads/writes are
+  unchanged.
+- **No new required dependency.** The `fs` adapter needs nothing; object-store
+  and edge adapters are optional.
+- **Local-first preserved.** Every machine keeps a complete local store and
+  works offline.
+- **Preview-first and auditable**, matching the existing maintenance model.
+
+---
+
+## 7. Open questions for maintainer direction
+
+1. Subcommand placement: extend `sync` (`sync store ...`) vs. a new top-level
+   verb, given `sync` already means rules sync.
+2. Journal representation: derive from existing columns for v1, or add an
+   explicit change-log table from the start.
+3. Which adapters belong in-tree vs. as optional/companion packages.
+4. Whether `serve-http` should be able to act as a sync remote for a user's own
+   machines, giving a self-hosted option that still keeps each client local.
+5. Merge policy defaults: is row-level LWW acceptable as the v1 default, with
+   lifecycle-aware overrides, or is a stricter policy preferred?
+
+The first implementation slice is released behind the opt-in CLI. It covers
+the project-scoped observation event path, filesystem/GitHub/S3/Postgres relay
+contracts, local outbox retry, clone detection, conflict evidence, and bounded
+keyset pulls. It does not enable background sync, upload private memory,
+replicate sessions/knowledge/CodeGraph tables, or claim that GitHub is a
+production database.

package/docs/PERFORMANCE.md

@@ -14,6 +14,32 @@ Memorix is designed to be light for everyday memory use and explicit about heavi
 
 The default memory path uses local SQLite as the canonical store and Orama for search/indexing. No cloud service is required.
 
+## Resource Safety Model
+
+Memorix does not impose a small maximum number of memories. SQLite remains the
+durable corpus, and large projects are processed in batches. The important
+limits are on **simultaneous work and disposable caches**, not on how much the
+user is allowed to remember.
+
+- A deferred vector backfill uses one cross-process worker lock per shared data
+  directory. Repeated hook events add to the durable queue; they do not spawn a
+  new Node process for every event.
+- A retrying vector job stays in cooldown. A provider outage therefore cannot
+  create a process storm every time another hook fires.
+- One backfill worker drains due vector jobs sequentially and releases its
+  SQLite/Orama state when it exits. A dead worker lock is recoverable by PID
+  liveness, with a long stale-lock fallback for interrupted filesystems.
+- Startup index hydration builds Orama documents in bounded batches and cached
+  vector attachment is also batched. This limits peak temporary allocations
+  without dropping durable observations.
+- The API embedding cache is a disposable working cache. Its default byte
+  budget is large and can be raised with `MEMORIX_EMBEDDING_CACHE_MAX_BYTES`,
+  but it is deliberately separate from the durable memory corpus. Cache
+  eviction never deletes a memory; a later vector backfill can regenerate it.
+- `serve-http` `/health` exposes `rss`, V8 heap, external memory, array-buffer
+  memory, and the V8 heap limit so a real saturation report can distinguish
+  JavaScript retention from native/model memory.
+
 ## Retrieval Profiles
 
 | Profile | Default? | Network work | Best fit |
@@ -78,6 +104,7 @@ On the release development machine used for this check, the healthy HTTP service
 | `MEMORIX_RERANK_TIMEOUT_MS` | 30000 | Bound HTTP and LLM rerank calls |
 | `MEMORIX_RERANK_PROVIDER` | `off` | Set `http` to enable optional HTTP rerank |
 | `MEMORIX_RERANK_BASE_URL` | `[memory.llm].base_url` | Compatible `/rerank` API root (path `/rerank` is appended) |
+| `MEMORIX_EMBEDDING_CACHE_MAX_BYTES` | `268435456` | Disposable in-process API-vector cache budget; raise for large warm caches, or lower when the host is memory constrained |
 | `memorix memory search --quality fast` | n/a | Force a fully local retrieval path for a latency-sensitive call |
 | `npm run benchmark:retrieval -- --records 1000 --runs 100` | n/a | Reproduce hot in-process lexical retrieval latency; not an end-to-end claim |
 | `npm run gate:large-store -- --records 40000` | n/a | Exercise SDK, HTTP MCP, hook persistence, cache integrity, and reopen behavior against a large isolated store |
@@ -98,6 +125,11 @@ On the release development machine used for this check, the healthy HTTP service
 - When Dashboard shows queued or failed maintenance work, inspect
   `/api/maintenance` on that local dashboard before assuming a Code Memory scan
   or lifecycle task completed.
+- When investigating CPU/RAM growth, inspect `memorix background status --json`
+  or `/health` first. Look for multiple `vector-backfill-runner` processes,
+  rising `rss` with stable heap, or rising V8 `heapUsed`; those indicate
+  different classes of problem and should not be “fixed” by lowering the
+  memory corpus limit.
 
 ## Large-Store Release Gate
 

package/docs/README.md

@@ -96,6 +96,7 @@ The public docs are organized by user intent:
 | 1.2 honest Lite and optional semantic CodeGraph provider contract | [1.2 Provider Quality](1.2.0-PROVIDER-QUALITY.md) |
 | 1.3 long-term memory model, source boundary, and lifecycle | [1.3 Memory Architecture](1.3-MEMORY-ARCHITECTURE.md) |
 | Active context-control work | [1.2.2 Memory Control Plane](1.2.2-MEMORY-CONTROL-PLANE.md) |
+| Multi-device memory sync plan and acceptance contract | [Multi-Device Sync](MULTI-DEVICE-SYNC-RESEARCH.md) |
 | 1.8.6 MCP compatibility acceptance contract | [1.8.0 Release Specification](1.8.0-RELEASE-CANDIDATE-SPEC.md) |
 | Historical cloud sync and multi-agent research | [CLOUD_SYNC_AND_MULTI_AGENT_RESEARCH.md](CLOUD_SYNC_AND_MULTI_AGENT_RESEARCH.md) |
 | Known issues and old roadmap notes | [KNOWN_ISSUES_AND_ROADMAP.md](KNOWN_ISSUES_AND_ROADMAP.md) |
@@ -124,8 +125,9 @@ Historical/deep-reference documents may describe older designs. If they conflict
 
 ## Current Product Line
 
-The current product line is **1.8.6**. The active next-line acceptance contract is
-[1.8.7 CodeGraph](1.8.7-CODEGRAPH.md); the published baseline remains 1.8.6.
+The current product line is **1.9.0**. Multi-device store sync is opt-in and
+keeps local SQLite canonical; existing users do not upload anything until they
+configure a relay provider explicitly.
 The authoritative acceptance contract for the current implementation is
 [1.8.0 Release Specification](1.8.0-RELEASE-CANDIDATE-SPEC.md).
 The current baseline has:

package/llms-full.txt

@@ -36,6 +36,7 @@ It installs the recommended Memorix integration for the target agent:
 - Gemini CLI: local Gemini extension package with MCP and `GEMINI.md` context.
 - OpenCode: local plugin file, `opencode.json` MCP config, OpenCode skill, and `AGENTS.md` guidance.
 - Grok Build: native lifecycle hooks in `~/.grok/hooks/memorix.json` and `~/.grok/AGENTS.md` guidance. Grok owns its MCP configuration; project hooks require `/hooks-trust`.
+- Multi-device sync: opt-in `memorix sync store status|push|pull` relays only qualified project-visible observation events. Local SQLite remains canonical; GitHub JSONL, filesystem, S3, and Postgres are transport options. Personal, agent-targeted, candidate, ephemeral, and other-project records are excluded by default.
 - Windsurf, Kiro, Antigravity, Trae: MCP config plus rules/hooks where supported.
 - DeepSeek Harness: MCP patch row (`$DSH_HOME/cordis.patch.yml`) plus `AGENTS.md` guidance and official skills.
 

package/llms.txt

@@ -15,6 +15,7 @@ Memorix gives coding agents persistent, project-aware memory across sessions, ID
 - `memorix` and `memcode` open memcode, the bundled terminal agent that uses the same project memory pool.
 - `memorix dashboard` opens the local read-mostly dashboard.
 - `memorix setup --agent grok --global` installs Grok's native lifecycle hooks and `AGENTS.md` guidance; Grok keeps MCP configuration under its own control.
+- `memorix sync store status|push|pull` is an opt-in project-scoped event relay; it never uploads the live SQLite database or WAL files.
 
 ## Memory Model
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "memorix",
   "mcpName": "io.github.AVIDS2/memorix",
-  "version": "1.8.9",
+  "version": "1.9.0",
   "description": "Local-first shared memory layer for AI coding agents across MCP clients, Git history, reasoning context, and project sessions.",
   "type": "module",
   "sideEffects": false,

package/plugins/antigravity/memorix/plugin.json

@@ -1,4 +1,4 @@
 {
   "name": "memorix",
-  "version": "1.8.9"
+  "version": "1.9.0"
 }

package/plugins/claude/memorix/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://anthropic.com/claude-code/plugin.schema.json",
   "name": "memorix",
-  "version": "1.8.9",
+  "version": "1.9.0",
   "description": "Shared workspace memory for Claude Code and other AI coding agents.",
   "author": {
     "name": "AVIDS2",

package/plugins/codebuddy/memorix/.codebuddy-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "memorix",
-  "version": "1.8.9",
+  "version": "1.9.0",
   "description": "Local-first project memory for CodeBuddy Code and other coding agents.",
   "author": {
     "name": "AVIDS2",

package/plugins/codex/memorix/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "memorix",
-  "version": "1.8.9",
+  "version": "1.9.0",
   "description": "Shared workspace memory for Codex and other AI coding agents.",
   "author": {
     "name": "AVIDS2",

package/plugins/copilot/memorix/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "memorix",
-  "version": "1.8.9",
+  "version": "1.9.0",
   "description": "Shared local workspace memory for GitHub Copilot CLI and other AI coding agents.",
   "author": {
     "name": "AVIDS2",

package/plugins/gemini/memorix/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "memorix",
-  "version": "1.8.9",
+  "version": "1.9.0",
   "mcpServers": {
     "memorix": {
       "command": "memorix",

package/plugins/hermes/memorix/plugin.yaml

@@ -1,5 +1,5 @@
 name: memorix
-version: "1.8.9"
+version: "1.9.0"
 description: Shared workspace memory bridge for Hermes Agent.
 author: AVIDS2
 license: Apache-2.0

package/plugins/omp/memorix/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memorix-omp-package",
-  "version": "1.8.9",
+  "version": "1.9.0",
   "description": "Memorix shared workspace memory package for Oh-my-Pi.",
   "license": "Apache-2.0",
   "keywords": [

package/plugins/openclaw/memorix/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "memorix",
-  "version": "1.8.9",
+  "version": "1.9.0",
   "description": "Shared workspace memory for OpenClaw and other AI coding agents.",
   "author": {
     "name": "AVIDS2",

package/plugins/pi/memorix/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memorix-pi-package",
-  "version": "1.8.9",
+  "version": "1.9.0",
   "description": "Memorix shared workspace memory package for Pi coding agent.",
   "license": "Apache-2.0",
   "keywords": [

package/server.json

@@ -7,7 +7,7 @@
     "url": "https://github.com/AVIDS2/memorix",
     "source": "github"
   },
-  "version": "1.8.9",
+  "version": "1.9.0",
   "websiteUrl": "https://mem.rglens.com",
   "icons": [
     {
@@ -22,7 +22,7 @@
     {
       "registryType": "npm",
       "identifier": "memorix",
-      "version": "1.8.9",
+      "version": "1.9.0",
       "runtimeHint": "npx",
       "packageArguments": [
         {

package/src/cli/command-guide.ts

@@ -209,7 +209,15 @@ const GUIDES: Record<string, CliCommandGuide> = {
   },
   sync: {
     summary: 'Synchronize agent rules and workspace artifacts through explicit routes.',
-    usage: ['memorix sync rules --action status', 'memorix sync workspace --action scan'],
+    usage: [
+      'memorix sync rules --action status',
+      'memorix sync workspace --action scan',
+      'memorix sync store status --json',
+      'memorix sync store push|pull [--dry] [--json]',
+      'memorix sync store compact --dry --through device=sequence',
+      'memorix sync store device rotate',
+    ],
+    notes: ['Store sync is opt-in, project-scoped, and never copies the live SQLite database.'],
   },
   ingest: {
     summary: 'Ingest Git and image evidence into project memory.',