memorio 4.9.35 → 5.0.0

package/README.md

@@ -1,132 +1,92 @@
 # 🧠 memorio
 
-**Local-first memory for JavaScript.**
-One import. Global state, local persistence, SQLite, semantic memory, optional sync.
+**Application state intelligence runtime.**
 
-[![npm version](https://img.shields.io/npm/v/memorio.svg)](https://www.npmjs.com/package/memorio)
-[![npm downloads](https://img.shields.io/npm/dm/memorio.svg)](https://www.npmjs.com/package/memorio)
-[![Socket Badge](https://socket.dev/api/badge/npm/package/memorio)](https://socket.dev/npm/package/memorio)
-[![Known Vulnerabilities](https://snyk.io/test/npm/memorio/badge.svg)](https://snyk.io/test/npm/memorio)
-[![zero deps](https://img.shields.io/badge/dependencies-0-brightgreen)](#security)
-[![license](https://img.shields.io/npm/l/memorio.svg)](#license)
+Use it like an object.
 
 ```ts
-import 'memorio'
+import 'memorio/global'
 
 state.user = { name: 'Sara', role: 'admin' }
 state.counter++
+
+console.log(state.user.name)
+console.log(state.counter)
 ```
 
 No provider tree. No reducers. No actions. No boilerplate.
 Just data, available where your application needs it.
 
-**And if you don't want a global API, don't use one:**
-
-```ts
-import { state, store, session, cache, idb, sqlite, memorio } from 'memorio'
-```
-
-The global API is a **choice**, not an architectural requirement.
-
 ---
 
-## Table of contents
-
-- [Why memorio](#why-memorio)
-- [Global is optional](#global-is-optional)
-- [Before / After](#before--after)
-- [Which layer should I use](#which-layer-should-i-use)
-- [Install](#install)
-- [Quick start](#quick-start)
-- [Observing changes](#observing-changes)
-- [The layers](#the-layers) — store · session · cache · idb · sqlite · memory
-- [Redux and other state managers](#redux-and-other-state-managers)
-  - [memorio vs Redux, at a glance](#memorio-vs-redux-at-a-glance)
-- [React integration](#react-integration)
-- [Typed state & schema validation](#typed-state--schema-validation)
-- [Local-first sync](#local-first-sync)
-- [Cross-platform support](#cross-platform-support)
-- [Security](#security)
-- [Honest limitations](#honest-limitations)
-- [When to use something else](#when-to-use-something-else)
-- [Design philosophy](#design-philosophy)
-- [A mental model](#a-mental-model)
-- [Recipes](#recipes)
-- [License](#license)
+## Why memorio?
 
----
+Most applications eventually need more than one kind of data: reactive state, persistent values, session data, caches, structured browser storage, local SQL, application memory, history, and optional sync.
 
-## Why memorio
+Usually that means a different library - and a different mental model - for each.
 
-Modern JavaScript applications often split their data across systems that don't talk to each other: a state manager, `localStorage`, `sessionStorage`, IndexedDB, a cache, SQLite, a server database, maybe an AI memory layer, maybe a sync layer on top. Each with its own API, its own lifecycle, its own mental model.
+**Memorio gives them one consistent runtime, without making the simple case complicated.**
 
-memorio brings these concerns into **one runtime and one consistent model**, while keeping each layer independent.
+```ts
+state.value = 42
+```
 
-| Layer | Purpose | Persistence | Reactive |
-|---|---|---:|---:|
-| `state` | application state | No | Yes |
-| `cache` | transient runtime data | No | No |
-| `session` | tab/session data | Yes | No |
-| `store` | persistent key/value data | Yes | No |
-| `idb` | durable structured browser data | Yes | No |
-| `sqlite` *(beta)* | relational local SQL | Optional | No |
-| `memory` | structured application memory | Yes | Optional |
-| `journal` *(beta)* | local-first operation history | Yes | No |
+Add persistence, memory, history, or sync only when your application actually needs them. The common case stays tiny; the runtime grows with you.
 
-Start with `state`. Add persistence or memory only when your application actually needs it.
+---
 
-## Global is optional
+## Install
 
-```ts
-import 'memorio'
-state.user = { name: 'Sara' }
+```bash
+npm install memorio
 ```
 
-is useful when an application benefits from a shared runtime and a simple API. But memorio does **not** require applications to expose or use global state — explicit imports work against the exact same runtime:
+Zero production dependencies in core. Optional integrations (`react`, `sql.js`, etc.) are installed only when you use them.
+
+---
+
+## Global or explicit
 
 ```ts
-import { state } from 'memorio'
+// Opt-in global access
+import 'memorio/global'
 state.user = { name: 'Sara' }
+
+// Or explicit imports
+import { state, store, memory } from 'memorio'
 ```
 
-This makes memorio suitable for small apps, modular apps, libraries, component systems, tests, or applications that already use another state manager and prefer explicit dependencies.
+Memorio never puts APIs on `globalThis` automatically and never infers dev mode from `NODE_ENV` or your bundler - global access is always something you choose.
 
-**Global when convenient. Explicit when appropriate.**
+---
 
-## Which layer should I use
+## The layers
 
-```text
-Does the UI need to react automatically to changes?
-│
-├─ Yes → state
-│
-└─ No
-   │
-   ├─ Only while the runtime exists?          → cache
-   ├─ Only for this browser tab/session?      → session
-   ├─ Small persistent key/value data?        → store
-   ├─ Larger or structured browser data?      → idb
-   ├─ Relations, joins, or SQL?               → sqlite
-   └─ Knowledge the application should
-      remember (confidence, source, expiry)?  → memory
-```
+| Layer     | Purpose                          | Persistence | Reactive |
+| --------- | --------------------------------- | :---------: | :------: |
+| `state`   | application state                 |     No      |   Yes    |
+| `cache`   | transient runtime data            |     No      |    No    |
+| `session` | tab/session data                  |    Yes      |    No    |
+| `store`   | persistent key/value data         |    Yes      |    No    |
+| `idb`     | durable structured browser data   |    Yes      |    No    |
+| `sqlite`  | relational local SQL              |  Optional   |    No    |
+| `memory`  | structured application memory     |    Yes      | Optional |
+| `journal` | local-first operation history     |    Yes      |    No    |
 
-## Install
+You don't have to use all of them - start with `state`.
 
-```bash
-npm install memorio
-```
-
-Optional peers, only loaded when used:
+**Which one do I need?**
 
-```bash
-npm install react react-dom   # React integration
-npm install sql.js            # sqlite engine
+```text
+Does the UI need to react automatically to changes?
+  yes → state
+  no  → cache (runtime only) · session (this tab) · store (small persistent kv)
+        idb (structured browser data) · sqlite (relations/SQL) · memory (what the app should remember)
 ```
 
-**Zero production dependencies** in the core package. See [Security](#security).
+---
 
-## Before / After
+## Before / after
 
 ```ts
 // Without memorio
@@ -138,445 +98,433 @@ useEffect(() => {
 useEffect(() => {
   localStorage.setItem('user', JSON.stringify(user))
 }, [user])
-```
 
-```ts
 // With memorio
-import 'memorio'
-store.set('user', { name: 'Sara' })   // persistent immediately, no boilerplate
-
-const user = store.get('user')
+import { state, persist } from 'memorio'
+state.user = { name: 'Sara' }
+const off = persist('state.user') // restores + keeps in sync
 ```
 
-Same result, one reactive line instead of two effects and manual JSON serialization.
+---
 
-## Quick start
+## Persistent state
 
 ```ts
-import 'memorio'
+import { state, persist } from 'memorio'
 
-state.user = { name: 'Sara', role: 'admin' }
-state.counter++
+state.user = { name: 'Sara' }
+const off = persist('state.user')
 
-console.log(state.user.name)
-console.log(state.counter)
+// later
+off()
 ```
 
-Reactive, Proxy-based state. No provider tree to configure, no reducer to maintain.
+Nested paths work when the intermediate objects already exist: `persist('state.user.preferences.theme')`.
+Without `localStorage` (e.g. Node), `store` falls back to memory.
 
-Lock a slice you don't want mutated by accident:
+---
+
+## Observing changes
 
 ```ts
-state.config = { maxUsers: 100 }
-state.config.lock()
+import { observer } from 'memorio'
 
-state.config.maxUsers = 200   // throws
+const off = observer('state.user', (next, previous) => {
+  console.log('user changed:', next, previous)
+})
 
-state.config.unlock()
-state.config.maxUsers = 200   // ok
+off() // unsubscribe
 ```
 
-Prefer explicit imports over the global? Same runtime either way:
+Prefer the returned `off()` for targeted teardown (it unsubscribes only *this* callback).
+The alternatives remove listeners by path name:
 
 ```ts
-import { state, store, session, cache, idb, sqlite, memorio } from 'memorio'
+observer.remove('state.user')   // removes ALL callbacks for this path
+observer.removeAll()           // removes every observer at once
 ```
 
-## Observing changes
+---
+
+## Application memory
 
-Reactivity is part of the runtime — it is not tied to React.
+State stores what the application **has**. Memory stores what it **remembers**.
 
 ```ts
-observer('state.user', (next, previous) => {
-  console.log('user changed:', next, previous)
+import { memorio } from 'memorio'
+
+await memorio.memory.remember('user.language', 'Italian', {
+  type: 'preference',
+  confidence: 0.92,
+  scope: 'local',
+  tags: ['user', 'ui'],
+  source: 'conversation'
 })
 
-// nested paths work too
-observer('state.user.name', callback)
+const language = await memorio.memory.recall('user.language')
 ```
 
-Lower-level event access is also available:
+Updating an entry doesn't overwrite it - the previous entry becomes `superseded`, the new one `active`:
 
 ```ts
-const off = memorio.dispatch.listen('state.user', event => console.debug(event.detail))
-memorio.dispatch.set('state.user', { detail: { name: 'Sara' } })
-
-off()   // remove only this subscription
+await memorio.memory.update('user.language', 'English', { confidence: 0.95 })
 ```
 
-Each subscription owns its own unsubscribe function. Prefer the returned `off()` over `memorio.dispatch.remove('state.user')`, which removes **all** listeners registered under that name.
-
-React apps get a dedicated hook, `useObserver` — see [React integration](#react-integration).
-
-## The layers
-
-### `store` — persistent key/value data
+Retrieve relevant memory instead of loading everything:
 
 ```ts
-store.set('preferences', { theme: 'dark' })
-const preferences = store.get('preferences')
+const context = await memorio.memory.context({
+  tags: 'user',
+  types: ['preference', 'decision'],
+  minConfidence: 0.7,
+  maxEntries: 10
+})
 ```
 
-Backed by `localStorage` in the browser. Falls back to memory in environments without persistent storage — check `store.isPersistent` when portability matters.
+> **Note:** "structured memory" here means metadata-based ranking (tags, type, confidence, recency) - not embedding similarity search. Pair `memorio.memory` with a dedicated vector store if you need that.
 
-### `session` — data for the current session
-
-```ts
-session.set('wizard-step', 3)
-const step = session.get('wizard-step')
+```text
+sqlite  → what data do I have?
+memory  → what does my application remember?
 ```
 
-Backed by `sessionStorage`. Good for multi-step workflows, temporary preferences, tab-scoped data.
+---
 
-### `cache` — volatile runtime data
+## The other layers, briefly
 
+**`store`** - persistent key/value, backed by `localStorage` in browsers, memory elsewhere.
 ```ts
-cache.set('expensive-result', computeExpensiveResult())
+store.set('preferences', { theme: 'dark' })
+const preferences = store.get('preferences')
 ```
 
-Disappears when the runtime disappears. No persistence guarantee, ever.
+**`session`** - scoped to the current browser session (`sessionStorage`). Good for wizard steps and tab-local state.
 
-### `idb` — durable structured browser data
+**`cache`** - volatile, in-memory, disappears when the runtime disappears.
 
+**`idb`** - durable structured browser data:
 ```ts
 await idb.db.create('app')
 await idb.table.create('app', 'users')
 await idb.data.set('app', 'users', { id: 1, name: 'Sara' })
+```
 
-const user = await idb.data.get('app', 'users', 1)
+**`sqlite`** - relational local SQL, in-memory by default via `sql.js`:
+```ts
+await sqlite.ready
+await sqlite.db.create('app', { persistence: true })
+await sqlite.query.run('app', `CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT, role TEXT)`)
+await sqlite.query.select('app', `SELECT * FROM users WHERE role = ?`, ['admin'])
 ```
+> ⚠️ Persistence serializes the **entire database** on flush - fine for small/medium datasets, but large ones need deliberate batching.
+
+Check what's actually available at runtime before depending on a backend: `memorio.getCapabilities()`.
+
+---
 
-Check runtime support before depending on it: `memorio.getCapabilities()`.
+## State Intelligence
 
-### `sqlite` — local SQL
+With history tracking enabled, mutations are recorded with a unique ID, HLC timestamp, source, and causal context - the foundation for undo/redo, diff, trace, and (planned) replay.
 
 ```ts
-await sqlite.ready
-await sqlite.db.create('app')
+import { memorio } from 'memorio'
+
+memorio.enableHistory(true)
 
-await sqlite.query.run('app', `
-  CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT NOT NULL, role TEXT)
-`)
-await sqlite.query.run('app', `INSERT INTO users (name, role) VALUES (?, ?)`, ['Sara', 'admin'])
+state.user = { name: 'John' }
+state.user.name = 'Maria'
+state.user.name = 'Pedro'
 
-const admins = await sqlite.query.select('app', `SELECT * FROM users WHERE role = ?`, ['admin'])
+const history = memorio.trace()
+memorio.undo()
+memorio.redo()
+
+memorio.canUndo()
+memorio.canRedo()
 ```
 
-Runs **in memory by default**, using `sql.js`. Persistence is explicit:
+**Explicit mutations & transactions:**
 
 ```ts
-await sqlite.db.create('app', { persistence: true })
+const mutation = memorio.mutate('state.user.role', 'admin', { source: 'permissions.enableAdmin' })
+// mutation.id · mutation.hlc · mutation.source
+
+const tx = memorio.transaction('user.migration', 'Migrate to v2 schema')
+state.user.role = 'admin'
+state.user.permissions = ['read', 'write']
+memorio.commitTransaction()
+
+// or abort and roll back
+memorio.transaction('failed-op')
+state.user.name = 'Maria'
+memorio.abortTransaction()
 ```
 
-> ⚠️ **Persistence is not incremental.** It serializes the **entire** database on flush — fine for small/medium local datasets, but large databases should not be persisted after every mutation. Batch writes and flush deliberately. memorio's SQLite layer is an embedded local SQL runtime, not a replacement for a server database.
+**Roadmap:**
 
-### `memory` — application memory
+| Phase | Capability                  | Status                                             |
+| ----- | ---------------------------- | --------------------------------------------------- |
+| 1     | Mutation Engine               | ✅ Active                                            |
+| 2     | Undo / Redo / Diff / Revert   | ✅ Partial (basic trace + undo/redo shipped above)   |
+| 3     | History Engine (persisted, queryable history) | Planned                       |
+| 4     | Replay / Time Machine          | Planned                                            |
+| 5     | Causal Graph                   | Planned                                            |
+| 6     | Explain / Trace / Impact       | Planned                                            |
+| 7     | What-if Simulation             | Planned                                            |
 
-The layer that makes memorio more than a state manager. `memory` represents information the application wants to **remember**, not just store — it can carry type, confidence, source, scope, tags, lifetime, status, and history.
+---
+
+## Typed state & validation
 
 ```ts
-await memorio.memory.remember('user.language', 'Italian', {
-  type: 'preference',
-  confidence: 0.92,
-  scope: 'local',
-  tags: ['user', 'ui'],
-  source: 'conversation',
-})
+import { memorio } from 'memorio'
 
-const language = await memorio.memory.recall('user.language')
-```
+interface AppState {
+  user: { name: string; age: number; email: string }
+  theme: 'light' | 'dark'
+}
 
-Updates don't overwrite — they supersede, preserving history:
+const app = memorio.typed<AppState>()
+app.theme = 'dark'   // ✅
+app.theme = 'purple'  // ❌ TypeScript error
 
-```ts
-await memorio.memory.update('user.language', 'English', { confidence: 0.95 })
-// previous entry → status: 'superseded'   |   new entry → status: 'active'
+app === state // same proxy, typed
 ```
 
-Retrieve what's relevant to the current operation, not everything:
+Runtime schemas validate values crossing trust boundaries:
 
 ```ts
-const context = await memorio.memory.context({
-  tags: 'user',
-  types: ['preference', 'decision'],
-  minConfidence: 0.7,
-  maxEntries: 10,
+memorio.registerSchema('user', {
+  type: 'object',
+  required: ['name', 'email'],
+  properties: {
+    name: { type: 'string', min: 1 },
+    email: { type: 'string', pattern: /^[^@]+@[^@]+$/ }
+  }
 })
-```
 
-The context system considers tags, type, confidence, and recency.
+memorio.registerSchema('tags', { type: 'array', items: { type: 'string' } })
+
+state.tags = ['a', 'b'] // accepted
+state.tags = [1, 2, 3]  // rejected
+```
 
-> ℹ️ **"Semantic" here means structured, not embedding-based.** `memory.context()` ranks by tags, type, confidence and recency — there is no hidden vector database and no claim that free text has been understood through embeddings. If you need true similarity search, pair a dedicated embedding/vector store with `memorio.memory` for the lifecycle on top (confidence, source, TTL, scope, history, supersession).
+---
 
-In short: `sqlite` answers "what data do I have?" — `memory` answers "what does my app remember, and how sure is it?" They're not competing for the same job.
+## React integration
 
-## Redux and other state managers
+`useObserver` is a thin bridge over the observer engine. For the common React case,
+wrap it in a tiny helper so components read state like any other value:
 
-memorio does not need to replace your existing state manager. Its Redux integration ships as a **separate, optional entry point**:
+```tsx
+import { useReducer } from 'react'
+import { useObserver, state } from 'memorio'
+
+// Subscribe to one or more state paths and re-render on change.
+function useMemorioValue(path: any) {
+  const [, update] = useReducer((n: number) => n + 1, 0)
+  useObserver(update, path)
+  return path
+}
 
-```ts
-import { createMemorioReduxBridge } from 'memorio/redux'
+function Counter() {
+  const counter = useMemorioValue(state.counter)
+  return <div>{counter}</div>
+}
 ```
 
-Redux is not a dependency of memorio — the adapter works against a small structural interface (`getState` / `subscribe` / `dispatch`), so it can work with Redux-style stores without coupling memorio's core to Redux.
+`useObserver` can also auto-discover dependencies — pass a callback with no explicit
+deps and it tracks every state path read inside it — but the explicit-deps form above
+is cheaper and easier to reason about at scale.
 
-> **Ownership rule:** your state manager owns application state. memorio owns memory.
+Memorio itself stays framework-independent - React is an integration, not a requirement.
 
-The bridge does not mirror the entire store — only explicitly mapped values are persisted:
+---
+
+## Redux and other state managers
+
+> **Your state manager owns application state. Memorio owns memory.**
 
 ```ts
+import { createMemorioReduxBridge } from 'memorio/redux'
+
 const memorioRedux = createMemorioReduxBridge<AppState>({
   mappings: {
     'user.preferences': {
       selector: state => state.user.preferences,
       type: 'preference',
       scope: 'local',
-      tags: ['app', 'user'],
+      tags: ['app', 'user']
     },
-    'user.name': state => state.user.name,
+    'user.name': state => state.user.name
   },
   whitelist: ['user/preferencesChanged', 'user/nameChanged'],
-  debug: true,
+  debug: true
 })
 
 const store = createStore(reducer, applyMiddleware(memorioRedux.middleware))
-```
 
-Hydration is explicit and one-shot:
-
-```ts
 await memorioRedux.hydrate(store, {
-  onHydration(values) {
-    store.dispatch(restorePreferences(values))
-  },
+  onHydration(values) { store.dispatch(restorePreferences(values)) }
 })
 ```
 
-Direction of ownership — there is intentionally no permanent two-way mirror:
-
 ```text
-Redux ─────────────→ memorio       memorio ────────────→ Redux
-application state     durable memory       bootstrap hydration
+Redux ─────────────→ memorio        memorio ───────────→ Redux
+application state    durable memory                     bootstrap hydration (one-shot)
 ```
 
-- only mapped selectors are persisted — the entire Redux tree is never mirrored
-- hydration is one-shot; restore dispatches do not create synchronization loops
-- persistence happens outside the reducer path; bursts of actions are coalesced
-- memorio failures do not break Redux dispatch — errors can be reported through `onError`
-- the adapter does not expose the memorio database through `globalThis` or DevTools
-
-### memorio vs Redux, at a glance
+The bridge persists only mapped selectors, never mirrors the full tree, coalesces bursts, and never breaks Redux dispatch if Memorio fails.
 
-Not a replacement — a different scope. Useful mainly for deciding which one (or both) fits a given piece of state.
-
-| | Redux | memorio |
+| | Redux | Memorio |
 |---|---|---|
-| Core model | single store, plain object | multiple independent layers (`state`, `store`, `session`, `cache`, `idb`, `sqlite`, `memory`) |
-| State changes | via dispatched actions + reducers | direct mutation on a reactive proxy |
-| Persistence | not built in (needs `redux-persist` or similar) | built into `store`/`session`/`idb`/`sqlite` |
-| Structured "memory" (confidence, TTL, source, supersession) | not a concept in Redux | native, via the `memory` layer |
-| Offline sync / conflict resolution | not built in | built into `memory.configure()` (operations + journal + HLC ordering) |
-| Time-travel debugging, strict middleware pipelines | yes, mature ecosystem | not a goal — see [When to use something else](#when-to-use-something-else) |
-| Dependencies | small core, large plugin ecosystem | zero production dependencies |
-
-Pick Redux when you need its action-pipeline discipline and tooling. Pick memorio when you want state, persistence, and structured memory under one runtime without wiring several libraries together. Nothing stops you from using both — that's exactly what the [Redux bridge](#redux-and-other-state-managers) is for.
-
-## React integration
-
-React is an integration, not a requirement — `useObserver` connects to the same observer system described above.
+| Core model | single store | independent runtime layers |
+| State changes | actions + reducers | direct reactive mutation |
+| Persistence | external integration | built in |
+| Structured memory | - | native |
+| Offline memory sync | - | supported |
+| Time-travel debugging | mature | State Intelligence (in progress) |
+| Production dependencies | ecosystem-dependent | zero in core |
 
-```tsx
-function Counter() {
-  const [, forceUpdate] = useReducer(x => x + 1, 0)
-  useObserver(forceUpdate, [state.counter])
-  return <div>{state.counter}</div>
-}
-```
-
-The runtime itself remains independent of React.
-
-## Typed state & schema validation
-
-TypeScript types give compile-time guarantees without creating another state container:
-
-```ts
-interface AppState {
-  user: { name: string; age: number; email: string }
-  theme: 'light' | 'dark'
-}
+Use Redux when you need its action-pipeline discipline and ecosystem. Use Memorio when you want state, persistence, and structured memory under one runtime. You can use both.
 
-const app = memorio.typed<AppState>()
-app.theme = 'dark'
-app.theme = 'purple'   // TypeScript error
-```
-
-`app === state` — same proxy, no duplicated store.
-
-Runtime validation protects values crossing trust boundaries:
-
-```ts
-memorio.registerSchema('user', {
-  type: 'object',
-  required: ['name', 'email'],
-  properties: {
-    name: { type: 'string', min: 1 },
-    email: { type: 'string', pattern: /^[^@]+@[^@]+$/ },
-  },
-})
-
-state.user = { name: 'Sara' }   // rejected: missing required "email"
-```
-
-Arrays validate each element via `items`:
-
-```ts
-memorio.registerSchema('tags', { type: 'array', items: { type: 'string' } })
-
-state.tags = ['a', 'b']   // accepted
-state.tags = [1, 2, 3]    // rejected
-```
+---
 
 ## Local-first sync
 
-The local application owns its data — the cloud is optional transport. memorio synchronizes **operations** (`remember`, `update`, `forget`, `expire`, `confirm`, `supersede`), not database dumps. A local journal records operations so temporary network failures don't stop the application from working.
+Memorio synchronizes **operations** (`remember`, `update`, `forget`, `expire`, `confirm`, `supersede`), not database dumps. A local journal keeps the app working through network failures; the cloud is optional transport, not a prerequisite.
 
 ```ts
 memorio.memory.configure({
   namespace: 'user:123:device:abc',
   provider: {
     push: ops => fetch('/api/sync', { method: 'POST', body: JSON.stringify(ops) }),
-    pull: since => fetch(`/api/sync?since=${since}`).then(r => r.json()),
+    pull: since => fetch(`/api/sync?since=${since}`).then(r => r.json())
   },
-  auto: true,
+  auto: true
 })
 ```
 
-```text
-local application → memorio memory → local journal → offline / cloud
-```
-
-The network is an extension of the local application, not its prerequisite.
-
-Remote operations are ordered causally using HLC timestamps. For concurrent writes to the same key, memorio provides a deterministic default — a custom resolver can override it:
+Concurrent operations use HLC ordering by default; override with a custom resolver:
 
 ```ts
 memorio.memory.configure({
   resolveConflict(local, remote) {
     if (remote.source === 'user-correction') return remote
     return local.confidence >= remote.confidence ? local : remote
-  },
+  }
 })
 ```
 
-Without a resolver, the default policy applies the remote entry on a tie. The resolver operates client-side — the sync provider is still responsible for any final server-side conflict policy.
+The sync provider is still responsible for the final server-side conflict policy.
+
+---
 
 ## Cross-platform support
 
-| API | Browser | Node.js | Deno | Edge / Workers |
-|---|:---:|:---:|:---:|:---:|
-| `state` / `observer` / `cache` | ✅ | ✅ | ✅ | ✅ |
-| `store` / `session` | persistent | memory fallback | memory fallback | capability-dependent |
-| `idb` | ✅ | ❌ | ❌ | capability-dependent |
-| `sqlite` | ✅ | ❌ | ❌ | capability-dependent |
-| `devtools` | dev-only | ❌ | ❌ | capability-dependent |
+| API                             | Browser    | Node.js          | Deno              | Edge / Workers        |
+| -------------------------------- | :--------: | :---------------: | :----------------: | :---------------------: |
+| `state` / `observer` / `cache`   |     ✅     |         ✅          |         ✅          |            ✅            |
+| `store` / `session`              | persistent | memory fallback   | memory fallback    | capability-dependent    |
+| `idb`                            |     ✅     |         ❌          |         ❌          | capability-dependent    |
+| `sqlite`                         |     ✅     |         ❌          |         ❌          | capability-dependent    |
+| `memory` / `journal`             |     ✅     |         ✅          |         ✅          |            ✅            |
+| `devtools`                       |  dev-only  |         ❌          |         ❌          | capability-dependent    |
 
 ```ts
 memorio.getCapabilities()
-memorio.isBrowser() / memorio.isNode() / memorio.isDeno() / memorio.isEdge()
+memorio.isBrowser() // .isNode() · .isDeno() · .isEdge()
 ```
 
-Do not assume every persistence backend exists in every runtime.
+Don't assume every persistence backend exists in every runtime - check first.
+
+> **SQLite on Node.js / Deno:** Memorio's `sqlite` is backed by `sql.js` (SQLite compiled to WebAssembly), which requires browser APIs (`window`, `document`, `WebAssembly`). It is not available in Node.js or Deno. For server-side SQL, pair Memorio with a native SQLite package directly; use `store` or `idb` for in-process persistence from Memorio.
+
+---
 
 ## Security
 
-- Zero production dependencies — [checked by Socket.dev](https://socket.dev/npm/package/memorio) and [scanned by Snyk](https://snyk.io/test/npm/memorio)
-- No `eval`, no dynamic code execution, no bundled telemetry
-- Sanitized keys, validated inputs, caught module-boundary errors
-- Bounded journal entries, UUID-based session identifiers
+Core has zero production dependencies. No `eval`, no dynamic code execution, no bundled telemetry, sanitized keys, validated inputs, bounded journal entries, UUID-based session identifiers. Independently checkable via Socket.dev / Snyk.
 
-> ⚠️ **memorio does not encrypt data by default.** This applies to `state`, `store`, `session`, `idb`, `memory`, and `sqlite`. Treat browser storage as client-controlled data — if your application handles auth secrets, credentials, or regulated data, bring your own encryption, backend authorization, and server-side security controls.
+> ⚠️ **Memorio does not encrypt data by default** - this applies to every layer (`state`, `store`, `session`, `idb`, `memory`, `sqlite`). Treat browser storage as client-controlled. Use proper encryption and backend authorization for credentials or regulated data.
 
-**Contexts are not security boundaries.** `memorio.createContext('tenant-123')` is useful for organizing and isolating application concerns — it is **not** an authorization mechanism. Code running inside the same JS runtime can potentially access other memorio contexts. Real tenant isolation belongs at the backend/authentication layer.
+**Contexts are not authorization:**
 
-memorio's DevTools are intended for development only, disabled via runtime detection (`process.env.NODE_ENV`) — not build-time removal. Make sure your bundler actually defines this correctly in production; don't treat DevTools absence as a security boundary.
+```ts
+memorio.createContext('tenant-123')
+```
 
-## Honest limitations
+Contexts organize and isolate application concerns - they're not a security boundary. Code in the same JS runtime can potentially reach other contexts. Real tenant isolation belongs at the auth/backend layer.
 
-memorio deliberately documents its edges.
+DevTools expose data for development only, and only when you opt into `memorio/global`.
 
-- **Semantic memory is structured, not vector-based.** `memory.context()` uses structured ranking, not embedding similarity search.
-- **SQLite persistence is not incremental** — the current strategy serializes the complete database on flush; large datasets need deliberate batching.
-- **Contexts and namespaces are not authorization** — they organize application data, they don't replace authentication or backend authorization.
-- **Data is not encrypted automatically** — memorio doesn't pretend local persistence is secure storage.
-- **DevTools are runtime-controlled, not build-removed** — production builds should still configure `NODE_ENV` correctly.
+---
 
 ## When to use something else
 
-memorio is intentionally not everything.
+- **A strict Redux-style architecture** - when you need action pipelines, extensive middleware, event-sourcing, or mature time-travel tooling. Memorio can integrate rather than replace.
+- **A server database** - for authoritative persistence, multi-user authorization, or server-side transactions.
+- **A dedicated vector database** - for true embedding similarity search. Memorio can still manage the lifecycle/metadata of what you retrieve from it.
+
+Memorio occupies a distinct space: **application state + history + causality + replay + impact analysis + simulation**. If you need to know *why* state changed, *who* changed it, or *what would happen* if it changed, Memorio is the tool - not just a state container.
 
-- **Need strict Redux-style architecture** (action pipelines, reducer-based transitions, extensive middleware, time-travel debugging, event-sourcing)? memorio can integrate with such systems rather than replace them.
-- **Need a server database** (authoritative persistence, multi-user authorization, server-side transactions, backend-controlled access)? Use one — memorio doesn't provide it.
-- **Need true embedding similarity / vector search**? Pair a dedicated vector database with `memorio.memory`, which can still manage the lifecycle and metadata of the retrieved knowledge.
+---
 
 ## Design philosophy
 
-1. **Local first** — the application stays useful when the network disappears.
-2. **Persistence is optional** — start in memory, persist only when it provides value.
-3. **The cloud is optional** — remote sync extends the local application; it does not define it.
-4. **Use the right primitive** — don't put relational data in a key/value store, or semantic memory in ordinary state.
-5. **Memory has meaning** — confidence, source, type, scope, TTL, tags, history, status. That's different from simply storing a value.
-6. **Global access is a convenience, not a requirement** — both `import 'memorio'` and `import { state } from 'memorio'` are valid; memorio does not impose one architecture.
-7. **Tell the truth about boundaries** — local data is not automatically secure, persistence is not authorization, structured memory is not automatically AI semantic search.
-8. **Keep the common case tiny:**
-   ```ts
-   import 'memorio'
-   state.value = 42
-   ```
-   Everything else is there when you need it.
-
-## A mental model
+1. **Local first** - the app stays useful when the network disappears.
+2. **Persistence is optional** - start in memory, persist only when it adds value.
+3. **The cloud is optional** - sync extends the local app; it doesn't define it.
+4. **Use the right primitive** - relational data belongs in SQL, not a kv store; memory isn't the same as ordinary state.
+5. **Memory has meaning** - confidence, source, type, scope, TTL, tags, history, status: more than "just a value."
+6. **Global access is explicit** - opt in with `import 'memorio/global'`, or keep it explicit with named imports.
+7. **Tell the truth about boundaries** - not encrypted, not authorization, not embedding search unless paired with one.
+8. **Keep the common case tiny** - `state.value = 42` is a complete, valid program.
 
-```text
-                         memorio
-                            │
-             ┌──────────────┼──────────────┐
-             │              │              │
-          runtime       persistence      memory
-             │              │              │
-       ┌─────┼─────┐   ┌────┼────┐    structured
-       │     │     │   │    │    │     knowledge
-     state cache session store idb sqlite
-       │
-    observer
-       │
-       ▼
-   application → journal → optional sync → cloud
-```
-
-The important part is not that memorio has many layers — it's that **you do not have to use them all**.
+---
 
-## Sneak Peek
+## Quick recipes
 
-### Making a `state` slice persistent
+```ts
+// Global state
+import 'memorio/global'
+state.user = { name: 'Sara', role: 'admin' }
 
-`state` is reactive but not persistent; `store` is persistent but not reactive. `persist()` bridges the two — it restores the value from `store` and then keeps the selected state path synchronized with it:
+// Explicit state
+import { state } from 'memorio'
+state.counter++
 
-```ts
-import 'memorio'
+// Persistent kv
+import { store } from 'memorio'
+store.set('preferences', { theme: 'dark' })
 
+// Persistent reactive state
+import { state, persist } from 'memorio'
 state.user = { name: 'Sara' }
+const off = persist('state.user')
 
-const off = persist('state.user')   // restore from store, then persist changes
-
-// later, e.g. on component unmount
-off()
-```
+// Application memory
+import { memorio } from 'memorio'
+await memorio.memory.remember('user.language', 'Italian', {
+  type: 'preference', confidence: 0.92, source: 'conversation'
+})
 
-`persist()` uses the same path syntax as `observer()`.
+// Observe a value
+import { observer } from 'memorio'
+const off = observer('state.user', (next, previous) => console.log(next, previous))
 
-Nested paths such as `state.user.preferences.theme` are supported, provided the intermediate objects already exist in `state`.
+// Track mutations, undo, and trace history
+import { memorio } from 'memorio'
+memorio.enableHistory(true)
+memorio.mutate('state.user.role', 'admin', { source: 'permissions.save' })
+const tx = memorio.transaction('migration', 'v2 schema migration')
+state.user.v2 = true
+memorio.commitTransaction()
+memorio.undo()
+console.debug(memorio.trace())
+```
 
-In environments without `localStorage` (Node/Deno/edge), `store` falls back to memory. `persist()` still works there, but persistence does not survive process or runtime restarts.
+---
 
 ## License