> **Status:** Published
> **Date:** 2026-09-12
> **Scope**: API Reference
> **Standard**: Memorio API Specification v5
>
---
# Synchronization & Cloud (optional)

`memorio.memory` is **local-first**. Data is created and served from the device;
the cloud is only ever a **transport/persistence provider**, never the source of
truth. Enabling sync does not replace local storage - it *mirrors* it.

```
                    memorio
                       │
              ┌────────┴────────┐
              │   Memory Engine │
              └────────┬────────┘
          ┌────────────┼────────────┐
          ▼            ▼            ▼
        local      SQLite         cloud
        memory     durable        sync
```

## 1. The rule: the data is born local

```ts
memorio.memory.remember('user.language', 'Italian', { scope: 'local' })
//        ↓ local first
//   store / sessionStorage / IndexedDB / sql.js
//        ↓ sync / push (when online)
//   cloud provider
```

The cloud therefore does not **replace** memory: it **replicates** it. This
gives you: offline-first, lowest latency, data available immediately,
synchronization when online, multi-device, multi-user, centralized persistence.

We deliberately do **not** provide:

```ts
// ❌ two mental models
memory.cloud.save(...)
```

Instead:

```ts
memorio.memory.remember('user.language', 'Italian')
// and a single configuration point:
memorio.memory.configure({ provider: myCloudProvider, namespace: '…' })
```

## 2. Namespace isolation (not a security boundary)

The journal is partitioned by a `namespace` string you pass to `configure()`.
All journal entries, pending operations, and replay calls for one namespace are
fully isolated from another - there is no API to enumerate or open a different
namespace's journal. You can use any naming convention, for example:

| Namespace pattern | Lifetime | Syncs by default |
|---|---|---|
| `device:<id>` | this browser/device only | no (sticky) |
| `user:<id>:device:<id>` | follows the user across devices | yes (requires provider) |
| `tenant:<id>:user:<id>` | shared across users / tenant | yes (requires provider) |

> As with `memorio.createContext`, **namespace scoping is a naming convention, not a
> security boundary.** Enforce real isolation server-side.

## 3. SQLite as the local durable store

SQLite (`sql.js`) is **in-memory by default** (volatie per page load). It becomes
the durable journal/value store when you opt in:

 - `sqlite.config({ persistence: true })` / `sqlite.db.create('app', { persistence: true })`
   snapshot the database to `store` (localStorage) and restore it on reopen.
 - Writes are journaled incrementally (append-only, HLC-timestamped) and
   checkpointed periodically (every 50 ops or 250 ms of idle). On reopen, the
   last checkpoint is loaded and the journal is replayed - no writes are lost.
 - `sqlite.db.persist(name)` / `sqlite.db.flush(name)` forces an immediate
   checkpoint; `sqlite.db.close(name)` checkpoints + closes;
   `sqlite.db.download(name, file?)` triggers a browser `.sqlite` download
   (dev convenience).

See `docs/markdown/SQLITE.md` for the full SQLite reference.

## 4. The local operation journal

The **sync journal** is the durable op log that drives cloud reconciliation.
It is persisted on `store` (localStorage) - **not** on an in-memory sql.js db,
because pending operations must survive a refresh for offline-first to work.

| Method | Returns | Notes |
|---|---|---|
| `memory.journal.append(entry, operation)` | `Promise<MemoryEntry>` | records `remember\|update\|forget\|expire\|confirm\|supersede\|delete\|patch` with `sync:'pending'` |
| `memory.journal.pending()` | `Promise<MemoryEntry[]>` | rows where `sync != 'synced'`, for the current namespace |
| `memory.journal.markSynced(ids)` | `Promise<number>` | advances rows to `synced` (namespace-scoped) |
| `memory.journal.get(id)` | `Promise<MemoryEntry \| null>` | single entry, namespace-scoped |
| `memory.journal.clear()` | `Promise<void>` | wipes the current namespace's journal |
| `memory.journal.replay()` | `Promise<SyncAck>` | pushes `pending()` to the provider, marks synced, optional `pull` |
| `memory.journal.status()` | `Promise<'store'>` | the substrate in use |

We sync **operations of memory**, never a raw database dump:

```
user A        device A
remember X ─────► local ─────► sync ─────► cloud
forget Z ──────► local ─────► sync ─────► cloud
```

## 5. Conflict resolution

The cloud must not simply say "last write wins." Memorio tags every entry with:

- `confidence` (0–1, user/system trust in the value)
- `lastConfirmedAt` / `updatedAt` (epoch ms)
- `version` (monotonic per-key counter)
- `source` / `scope`

Remote conflicts are surfaced as `sync:'conflict'` rows via
`journal.pending()`; the provider's `resolveConflict(local, remote)` hint decides
which entry wins. Example:

```
Laptop:  language=Italian, confidence=0.92
Phone:   language=English, confidence=0.61
→ higher-confidence entry wins locally; the provider decides for shared scope.
```

## 6. Configuring a backend

Sync is **opt-in**. You supply an application-owned `provider` that knows how to
talk to your backend (REST, WebSocket, Supabase, a custom agent server, …).

```ts
memorio.memory.configure({
  namespace: 'user:123:device:abc',   // tenant/user/device - partitions the journal
  provider: {
    push(ops) { return fetch('/api/sync', { method: 'POST', body: JSON.stringify(ops), headers: authHeaders }) }
    pull(since) { return fetch(`/api/sync?since=${since}`).then(r => r.json()) }
    resolveConflict(local, remote) { return (local.confidence ?? 0) >= 0.8 ? 'local' : 'remote' }
  },
  auto: true                           // auto-replay on focus/online (default true)
})
```

```ts
interface SyncProvider {
  push(ops: MemoryEntry[]): Promise<{ synced: string[]; conflicts?: string[]; error?: string }>
  pull?(since?: number): Promise<MemoryEntry[]>
  resolveConflict?(local: MemoryEntry, remote: MemoryEntry): Promise<'local' | 'remote' | 'merge'>
}
```

## 7. Security (NIST / OWASP / NSA posture)

- **Memorio never handles credentials.** No passwords, tokens, or API keys are
  read from or stored by memorio. Authentication/authorization live in your
  `provider`/backend (OWASP A01: Broken Access Control).
- **Namespace isolation.** The journal is keyed by `namespace:id` at the storage
  layer; there is **no API** to enumerate or open another namespace's journal. A
  client holding a forged/fake namespace simply sees its own (empty) journal.
- **No dynamic code.** Journal entries are strictly JSON-round-tripped,
  size-capped (10 MB/entry), and never `eval`'d. The sql.js loader never
  `import()`s a bare specifier that could be hijacked at build time.
- **Trust boundary:** memorio owns the local durable copy + operation log; the
  provider/backend owns remote-side auth and conflict resolution. Memorio
  surfaces `conflict`/`error` rows; it does not fabricate a winner.
- **Data-at-rest (NSA/CISA).** memorio's `store`/`idb`/`sqlite` snapshots are
  **not encrypted**. If you persist user data server-side or ship it through your
  backend, encrypt it server-side with keys you manage - memorio treats the local
  store as untrusted-from-the-browser and does not attest its own integrity.

## 8. Where data lives

| Substrate | API | Volatile? | Persistent? |
|---|---|---|---|
| in-memory `Proxy` | `state` | yes (per tab) | no |
| `localStorage` / Map | `store` | no | yes (browser) |
| `sessionStorage` / Map | `session` | no | per-tab (browser) |
| IndexedDB | `idb`, `memory` durable | no | yes |
| sql.js (WASM heap) | `sqlite` | **yes** | with `persistence: true` (journal + checkpoint → `store`) |
| sync journal | `memory.journal` | no | yes (`store`) |

---

## 9. Evolving the journal toward multi-device consistency

Moving from sequential, single-device sync to concurrent offline edits across
multiple devices is a classic local-first challenge. Below are six
architectural strategies, in increasing order of sophistication, that can be
layered onto the existing journal **without** adopting a full CRDT framework
(Yjs, Automerge, etc.).

> **Scope note.** These strategies target `memorio.memory` first - it already
> carries the metadata a journal needs (`confidence`, `source`, `tags`, `scope`,
> `createdAt`, `lastConfirmedAt`). If synchronization is ever extended to
> `state` or `store`, those layers must gain HLC timestamps and path-level
> fields explicitly - they cannot inherit them from `memory`.

### 9.1 Field-level / path-level journaling

Recording an entire entity in the journal makes orthogonal edits un-mergeable:

```json
{ "op": "set", "path": "user.role", "value": "admin", "timestamp": 1710000000 }
```

Device A writes `user.name`, device B writes `user.role` - both are patch
operations on the **same entity**. An entity-level journal would produce one
opaque `UPDATE user = {…}` and one write would clobber the other. Path-level
patches merge automatically because the paths are disjoint.

> **Not a panacea.** Path-level journaling merges edits to *different* fields.
> Two devices writing the **same** path concurrently still need explicit conflict
> resolution (Section 5). HLC tells you *when* the events happened; it does not
> tell you *which value wins* when events are truly concurrent on the same path.

### 9.2 Causal ordering with Hybrid Logical Clocks (HLC)

Wall-clock timestamps alone fail under clock drift. Associate every journal
entry with an HLC that combines a physical component, a logical counter, and a
node identifier:

```
hlc:1710000005:2:deviceB
```

This gives constant-size causal ordering (vs. vector clocks, which grow with
the number of writers - problematic for a bounded journal). The sync engine can
then apply causally-dependent operations in order and invoke the conflict
resolver only for genuinely concurrent writes on the same path.

### 9.3 Ordering collections without full OT - fractional indexing

Arrays and ordered lists are the hardest non-CRDT case. Numeric indices shift
when a peer inserts or deletes nearby. Two lightweight options:

1. **Keyed collections** - treat list items as a `Map<id, value>` rather than a
   positional array. No index renumbering needed.
2. **Fractional indexing** - assign each element a sortable key between its
   neighbours (e.g. `1.0`, `2.0` → insert at `1.5`). On repeated re-inserts
   between the same pair, keys grow in length and should be rebalanced
   periodically. Use a mature library (`fractional-indexing` on npm) rather than
   reimplementing the arithmetic.

### 9.4 Explicit deletions (tombstones)

A bare "remove" entry can be resurrected as a "zombie" when a concurrent
update is replayed after it. Instead, record every `forget` / `delete` as a
first-class journal event with its own HLC:

```json
{ "op": "delete", "path": "user.role", "timestamp": "hlc:1710000005:0:deviceA" }
```

The tombstone participates in the same causal comparison as `set` events: if
the delete's HLC succeeds the update's, the field is gone; if it precedes, the
update is re-applied. Keep tombstones around until all known peers have
acknowledged them, then garbage-collect during a maintenance sweep.

### 9.5 Hybrid sync - server-assisted consensus

Since memorio's cloud role is transport-and-acknowledgement (not source of
truth), the backend can resolve conflicts on the server and return the
canonical sequence:

| Pattern | Description |
|---|---|
| **Optimistic local apply** | Apply the local journal entry immediately and emit reactive events. |
| **Server ack** | Backend validates causal order against the central state and returns the official sequence. |
| **Client journal rebase** | Confirmed entries are purged from the local journal; unconfirmed local entries are replayed on top of the acknowledged state. |

### 9.6 Validation - convergence simulation

Causal correctness is theoretical until you test it across replay orderings:

- Generate random concurrent `set` / `delete` operations across N simulated
  devices (shared paths and disjoint paths).
- Replay the operation log in every plausible ordering on each simulated
  device.
- Assert **state convergence**: every device arrives at the same final state
  regardless of delivery order.
- Include hand-crafted pathological cases (`update` vs concurrent `delete` on
  the same path, `insert` vs concurrent `delete` on the same array index,
  interleaved reorders).

### 9.7 Migration

Path-level journal entries with HLC and tombstones are a format change from
entity-level entries. Mitigate with:

- An explicit **version header** on every journal entry.
- A clear migration policy: either a one-time compaction pass that folds
  legacy entity-level entries into the current state and starts a fresh
  journal, or a dual-format reader that can replay both formats during the
  transition window.

### 9.8 Recommended architecture diagram

```text
[ Local Mutation ]
        │
        ▼
[ Field-Level Patch (set/delete) + HLC Timestamp ]
        │
        ├───► Local State (immediate reactive update)
        │
        └───► Local Journal (incl. tombstones for deletes)
                    │
             (Online Sync)
                    │
                    ▼
        [ Backend Conflict Resolver ]
        (concurrent path → resolveConflict;
         otherwise apply in HLC order)
                    │
                    ▼
        [ State Ack / Rebased Journal ]
```

Applying granular path-level patches, HLC for causality, fractional indexing
for ordered collections, explicit tombstones for deletions, and a convergence
test suite lets memorio handle high-frequency concurrent offline edits across
devices without the overhead of a full CRDT stack.
