memorio 4.9.30 → 4.9.35

package/README.md

@@ -18,18 +18,30 @@ state.counter++
 ```
 
 No provider tree. No reducers. No actions. No boilerplate.
-Just data that exists where your application needs it — and grows with it.
+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) — state · store · session · cache · idb · sqlite · memory
+- [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)
@@ -38,62 +50,105 @@ Just data that exists where your application needs it — and grows with it.
 - [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
 
-Modern apps usually split their data across systems that don't talk to each other: a state manager, `localStorage`, `sessionStorage`, IndexedDB, a database, a cache, maybe an AI memory layer, maybe a sync layer on top. Each with its own API, its own mental model, its own edge cases.
+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 these concerns **one runtime and one mental model** — without forcing you to use all of it.
+memorio brings these concerns into **one runtime and one consistent model**, while keeping each layer independent.
 
-| Layer | Purpose | Maturity |
-|---|---|---|
-| `state` | reactive volatile application state | Stable |
-| `cache` | transient runtime data | Stable |
-| `session` | session-scoped persistence | Stable |
-| `store` | persistent key/value data | Stable |
-| `idb` | durable structured browser data | Stable |
-| `sqlite` | relational data & SQL | Beta |
-| `memory` | semantic app/agent memory | Beta |
-| `journal` | local-first operation history | Beta |
+| 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 |
+
+Start with `state`. Add persistence or memory only when your application actually needs it.
+
+## Global is optional
+
+```ts
+import 'memorio'
+state.user = { name: 'Sara' }
+```
+
+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:
+
+```ts
+import { state } from 'memorio'
+state.user = { name: 'Sara' }
+```
 
-Start with `state`. Add the rest only when your app actually needs it.
+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.
+
+**Global when convenient. Explicit when appropriate.**
 
 ## Which layer should I use
 
 ```text
 Does the UI need to react automatically to changes?
 │
-├─ Yes → state, or a memory-backed reactive slice
+├─ Yes → state
 │
-└─ No, I just need to store/retrieve a value
-   │
-   ├─ Survive a reload?
-   │  ├─ No               → cache
-   │  ├─ This tab only    → session
-   │  └─ Yes, indefinitely→ store (small) or idb (larger/structured)
+└─ No
    │
-   ├─ Need relations, joins, SQL?          → sqlite
-   └─ Is this "knowledge" the app reasons
-      about (confidence, source, expiry)?  → memory
+   ├─ 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
 ```
 
 ## Install
 
 ```bash
-npm i memorio
+npm install memorio
 ```
 
 Optional peers, only loaded when used:
 
 ```bash
-npm i react react-dom   # React integration
-npm i sql.js            # SQLite engine
+npm install react react-dom   # React integration
+npm install sql.js            # sqlite engine
+```
+
+**Zero production dependencies** in the core package. See [Security](#security).
+
+## Before / After
+
+```ts
+// Without memorio
+const [user, setUser] = useState(null)
+useEffect(() => {
+  const saved = localStorage.getItem('user')
+  if (saved) setUser(JSON.parse(saved))
+}, [])
+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')
 ```
 
-**Zero production dependencies.** See [Security](#security).
+Same result, one reactive line instead of two effects and manual JSON serialization.
 
 ## Quick start
 
@@ -101,16 +156,24 @@ npm i sql.js            # SQLite engine
 import 'memorio'
 
 state.user = { name: 'Sara', role: 'admin' }
-const name = state.user.name
+state.counter++
+
+console.log(state.user.name)
+console.log(state.counter)
 ```
 
-Reactive, in-memory, Proxy-based, globally accessible. Lock a slice you don't want mutated by accident:
+Reactive, Proxy-based state. No provider tree to configure, no reducer to maintain.
+
+Lock a slice you don't want mutated by accident:
 
 ```ts
 state.config = { maxUsers: 100 }
 state.config.lock()
+
 state.config.maxUsers = 200   // throws
+
 state.config.unlock()
+state.config.maxUsers = 200   // ok
 ```
 
 Prefer explicit imports over the global? Same runtime either way:
@@ -121,7 +184,7 @@ import { state, store, session, cache, idb, sqlite, memorio } from 'memorio'
 
 ## Observing changes
 
-Reactivity isn't a React add-on — it's built into the runtime. Watch any state path directly, in any environment:
+Reactivity is part of the runtime — it is not tied to React.
 
 ```ts
 observer('state.user', (next, previous) => {
@@ -132,102 +195,40 @@ observer('state.user', (next, previous) => {
 observer('state.user.name', callback)
 ```
 
-`dispatch` is the event mechanism underneath it, if you need to hook in lower-level:
+Lower-level event access is also available:
 
 ```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
-memorio.dispatch.remove('state.user')   // remove all subscriptions on a name
+off()   // remove only this subscription
 ```
 
-Multiple subscribers on the same path each keep firing — each `listen` returns
-its own unsubscribe. Prefer the returned `off()` over `remove()` for per-caller
-teardown, since `remove()` clears *every* listener registered under that name.
-
-`observer` paths are runtime strings — for compiler-checked access, see [typed state](#typed-state--schema-validation).
+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).
 
-## Redux / state-manager integration
-
-Memorio ships its Redux integration as a **separate, optional entrypoint** (`memorio/redux`). It is
-*not* part of core and is **never imported by `import memorio from 'memorio'`** — so applications
-that don't use Redux pay nothing. Redux is neither a dependency of Memorio nor of the adapter: the
-adapter talks to any store that satisfies a tiny structural shape (`getState` / `subscribe` /
-`dispatch`), so `redux`, Redux Toolkit, Zustand, NgRx, etc. are all accepted without importing the
-`redux` types.
-
-> **Ownership rule:** *Redux owns application state. Memorio owns memory.* The adapter only writes
-> **selected** values (declared opt-in mappings) into Memorio memory, and only recalls them once,
-> at bootstrap. It never mirrors the whole Redux tree and never two-way syncs.
-
-```ts
-import memorio from 'memorio'
-import { createMemorioReduxBridge } from 'memorio/redux'
-
-type AppState = { user: { name: string; preferences?: { theme?: string } } }
-
-const memorioRedux = createMemorioReduxBridge<AppState>({
-  // Opt-in: only these paths become durable memory.
-  mappings: {
-    'user.preferences': {
-      selector: (s) => s.user.preferences,
-      type: 'preference',
-      scope: 'local',          // never 'hot' for Redux mappings
-      tags: ['app', 'user']
-    },
-    'user.name': (s) => s.user.name   // a bare selector is also accepted
-  },
-  // Performance: only consider the action types that can mutate mapped state.
-  whitelist: ['user/preferencesChanged', 'user/nameChanged'],
-  // Diagnostics
-  debug: true
-})
-
-const store = createStore(reducer, applyMiddleware(memorioRedux.middleware))
-
-// Bootstrap hydration (Memorio -> Redux, one-shot). The bridge arms a
-// re-entrancy guard so the restore dispatch does not echo back to Memorio.
-await memorioRedux.hydrate(store, {
-  onHydration: (values) => store.dispatch(restorePreferences(values))
-})
-```
-
-Directional flow, no loops:
-
-| Direction | Mechanism | Ownership |
-| --- | --- | --- |
-| Redux -> Memorio | middleware persists only `mappings` whose selector changed **and** whose action type isn't blacklisted (#30) | Memorio is the durable owner (#31) |
-| Memorio -> Redux | `hydrate()` recalls once at bootstrap; the app dispatches its own restore actions | Redux owns runtime state |
-
-- **No store mirroring:** only mapped selectors are persisted — never `store.getState()` wholesale.
-- **No synchronization loops:** hydration arms `setHydrating(true)` + seeds the change-detection cache, so the restore dispatch is seen as "no change" and is not re-persisted.
-- **Async is off the reducer path:** middleware defers `memorio.memory.remember` to a microtask and coerces a burst of actions into a single flush.
-- **Failure-isolated:** Memorio errors are swallowed by default (`failSoft: true`, default) and routed to `onError`; Redux dispatch always completes normally.
-- **Production-safe:** nothing in the adapter exposes Memorio's database on `globalThis` / DevTools.
-
 ## The layers
 
-### `store` — persistent key/value
+### `store` — persistent key/value data
 
 ```ts
 store.set('preferences', { theme: 'dark' })
 const preferences = store.get('preferences')
 ```
 
-Backed by `localStorage` in the browser (`store.isPersistent === true`); falls back to memory elsewhere.
+Backed by `localStorage` in the browser. Falls back to memory in environments without persistent storage — check `store.isPersistent` when portability matters.
 
-### `session` — follows the tab
+### `session` — data for the current session
 
 ```ts
-session.set('token', 'user-abc-123')
+session.set('wizard-step', 3)
+const step = session.get('wizard-step')
 ```
 
-Backed by `sessionStorage`. Good for auth state, wizards, tab-scoped data.
+Backed by `sessionStorage`. Good for multi-step workflows, temporary preferences, tab-scoped data.
 
-### `cache` — volatile, fast
+### `cache` — volatile runtime data
 
 ```ts
 cache.set('expensive-result', computeExpensiveResult())
@@ -235,18 +236,19 @@ cache.set('expensive-result', computeExpensiveResult())
 
 Disappears when the runtime disappears. No persistence guarantee, ever.
 
-### `idb` — durable, structured
+### `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)
 ```
 
-Check before relying on it in portable code: `memorio.getCapabilities()`.
+Check runtime support before depending on it: `memorio.getCapabilities()`.
 
-### `sqlite` — a real local SQL engine
+### `sqlite` — local SQL
 
 ```ts
 await sqlite.ready
@@ -260,17 +262,17 @@ await sqlite.query.run('app', `INSERT INTO users (name, role) VALUES (?, ?)`, ['
 const admins = await sqlite.query.select('app', `SELECT * FROM users WHERE role = ?`, ['admin'])
 ```
 
-Runs **in memory by default**, powered by `sql.js` (lazy-loaded — see [loading strategies](#cross-platform-support)). Enable persistence explicitly when you need it:
+Runs **in memory by default**, using `sql.js`. Persistence is explicit:
 
 ```ts
 await sqlite.db.create('app', { persistence: true })
 ```
 
-> ⚠️ Persistence serializes the **entire** database on each flush — it is not incremental. Fine for small/medium data; for larger datasets, persist deliberately after a batch of writes, not on every mutation. See [Honest limitations](#honest-limitations).
+> ⚠️ **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.
 
-### `memory` — semantic application memory
+### `memory` — application memory
 
-The layer that makes memorio more than a state manager. Structured memory with type, confidence, TTL, tags, source, scope, and a real lifecycle:
+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.
 
 ```ts
 await memorio.memory.remember('user.language', 'Italian', {
@@ -284,14 +286,14 @@ await memorio.memory.remember('user.language', 'Italian', {
 const language = await memorio.memory.recall('user.language')
 ```
 
-Updates don't overwrite — they **supersede**, preserving history:
+Updates don't overwrite — they supersede, preserving history:
 
 ```ts
 await memorio.memory.update('user.language', 'English', { confidence: 0.95 })
-// old entry → status: 'superseded'   |   new entry → status: 'active'
+// previous entry → status: 'superseded'   |   new entry → status: 'active'
 ```
 
-Retrieve what's *relevant*, not everything:
+Retrieve what's relevant to the current operation, not everything:
 
 ```ts
 const context = await memorio.memory.context({
@@ -302,13 +304,86 @@ const context = await memorio.memory.context({
 })
 ```
 
-> ℹ️ **"Semantic" here means structured, not embedding-based.** `memory.context()` ranks by tags, type, confidence and recency — there's no vector similarity search under the hood (yet — see [roadmap](#honest-limitations)). Need true meaning-based retrieval over free text? Pair this layer with your own embedding store and use `memorio.memory` for the lifecycle (confidence, TTL, supersession) on top.
+The context system considers tags, type, confidence, and recency.
 
-`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.
+> ℹ️ **"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.
+
+## Redux and other state managers
+
+memorio does not need to replace your existing state manager. Its Redux integration ships as a **separate, optional entry point**:
+
+```ts
+import { createMemorioReduxBridge } from 'memorio/redux'
+```
+
+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.
+
+> **Ownership rule:** your state manager owns application state. memorio owns memory.
+
+The bridge does not mirror the entire store — only explicitly mapped values are persisted:
+
+```ts
+const memorioRedux = createMemorioReduxBridge<AppState>({
+  mappings: {
+    'user.preferences': {
+      selector: state => state.user.preferences,
+      type: 'preference',
+      scope: 'local',
+      tags: ['app', 'user'],
+    },
+    'user.name': state => state.user.name,
+  },
+  whitelist: ['user/preferencesChanged', 'user/nameChanged'],
+  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))
+  },
+})
+```
+
+Direction of ownership — there is intentionally no permanent two-way mirror:
+
+```text
+Redux ─────────────→ memorio       memorio ────────────→ Redux
+application state     durable memory       bootstrap hydration
+```
+
+- 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
+
+Not a replacement — a different scope. Useful mainly for deciding which one (or both) fits a given piece of state.
+
+| | 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` is a thin bridge onto the same `observer` mechanism from above:
+React is an integration, not a requirement — `useObserver` connects to the same observer system described above.
 
 ```tsx
 function Counter() {
@@ -318,9 +393,11 @@ function Counter() {
 }
 ```
 
+The runtime itself remains independent of React.
+
 ## Typed state & schema validation
 
-TypeScript types for compile-time safety:
+TypeScript types give compile-time guarantees without creating another state container:
 
 ```ts
 interface AppState {
@@ -330,12 +407,12 @@ interface AppState {
 
 const app = memorio.typed<AppState>()
 app.theme = 'dark'
-app.theme = 'purple'   // ❌ TypeScript error
+app.theme = 'purple'   // TypeScript error
 ```
 
-`app === state` — same Proxy, no duplicated store.
+`app === state` — same proxy, no duplicated store.
 
-Runtime validation for values crossing trust boundaries:
+Runtime validation protects values crossing trust boundaries:
 
 ```ts
 memorio.registerSchema('user', {
@@ -347,41 +424,40 @@ memorio.registerSchema('user', {
   },
 })
 
-state.user = { name: 'Sara' }   // rejected — missing required "email"
+state.user = { name: 'Sara' }   // rejected: missing required "email"
 ```
 
-Array item validation is supported per-element with the `items` schema field:
+Arrays validate each element via `items`:
 
 ```ts
-memorio.registerSchema('tags', {
-  type: 'array',
-  items: { type: 'string' },
-})
+memorio.registerSchema('tags', { type: 'array', items: { type: 'string' } })
 
 state.tags = ['a', 'b']   // accepted
-state.tags = [1, 2, 3]    // rejected — items must be strings
+state.tags = [1, 2, 3]    // rejected
 ```
 
 ## Local-first sync
 
-The local application owns its data; the cloud is optional transport.
-
-memorio syncs **operations** (`remember`, `update`, `forget`, `expire`, `confirm`, `supersede`), not database dumps, via a local journal that survives network failure:
+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.
 
 ```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()),
+    push: ops => fetch('/api/sync', { method: 'POST', body: JSON.stringify(ops) }),
+    pull: since => fetch(`/api/sync?since=${since}`).then(r => r.json()),
   },
   auto: true,
 })
 ```
 
-When `replay()` pulls remote operations, entries are ordered causally by HLC timestamp. For
-*concurrent* writes to the same key (an HLC tie) the **remote entry wins by default**; provide a
-`resolveConflict` to override:
+```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:
 
 ```ts
 memorio.memory.configure({
@@ -392,66 +468,115 @@ memorio.memory.configure({
 })
 ```
 
-When no resolver is supplied, Memorio logs a warn (dev only) and applies the remote entry on a
-tie. The resolver only settles *client-side* divergence between what memorio has seen locally —
-the provider is still responsible for the final server-side policy.
+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.
 
 ## 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 |
+| `devtools` | dev-only | ❌ | ❌ | capability-dependent |
 
 ```ts
 memorio.getCapabilities()
-memorio.isBrowser() / isNode() / isDeno() / isEdge()
+memorio.isBrowser() / memorio.isNode() / memorio.isDeno() / memorio.isEdge()
 ```
 
+Do not assume every persistence backend exists in every runtime.
+
 ## Security
 
-- Zero production dependencies — [verified by Socket.dev](https://socket.dev/npm/package/memorio) and [scanned by Snyk](https://snyk.io/test/npm/memorio)
+- 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
-- UUID-based session identifiers, bounded journal entries
+- Bounded journal entries, UUID-based session identifiers
 
-**What memorio does *not* do:** it does not encrypt `state`, `store`, `session`, `idb`, local memory, or SQLite contents. Treat browser storage as client-controlled data. If you handle auth tokens, secrets, or regulated data, bring your own encryption and backend security.
+> ⚠️ **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.
 
-**Contexts, scopes, and namespaces are not security boundaries.** `memorio.createContext('tenant-123')` is for code organization — anything in the same JS runtime can, in principle, reach any context through the memorio API. Real tenant isolation belongs at the backend/auth layer.
+**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.
+
+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.
 
 ## Honest limitations
 
-We'd rather tell you where the edges are than have you find them in production.
+memorio deliberately documents its edges.
 
-- **`memory.context()` is rule-based, not embedding-based.** No free-text semantic similarity yet — see [roadmap](#when-to-use-something-else).
-- **SQLite persistence is a full serialize-on-flush**, not incremental. Costly for large datasets if triggered on every write.
-- **Namespaces and contexts are organizational, not authorization boundaries.**
-- **Nothing is encrypted by default**, anywhere.
-- **DevTools are dev-only by runtime detection** (`process.env.NODE_ENV`), not a build-time strip — double-check your bundler actually sets this in production.
+- **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
 
-- **Need strict Redux-style architecture** (action pipelines, middleware, time-travel debugging) → use a dedicated Redux-style setup.
-- **Need hard security isolation** → real backend authorization, process isolation, encryption. Don't lean on memorio contexts.
-- **Need durable server storage** → Node/edge runtimes don't gain browser persistence for free. Use a server database.
-- **Need true semantic/embedding retrieval** → pair `memorio.memory` with a dedicated embedding store; use memorio for the lifecycle metadata on top.
+memorio is intentionally not everything.
+
+- **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 app stays useful when the network disappears.
-2. **Persistence is incremental** — start with memory, persist only when useful.
-3. **The cloud is optional** — an extension, never a prerequisite.
-4. **Choose 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, lifetime, scope, type, history.
-6. **Tell the truth about boundaries** — volatile, unencrypted, not-a-security-boundary: say so, everywhere it applies.
-7. **Keep the common case tiny**:
+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
+
+```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
+
+### Making a `state` slice persistent
+
+`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:
+
+```ts
+import 'memorio'
+
+state.user = { name: 'Sara' }
+
+const off = persist('state.user')   // restore from store, then persist changes
+
+// later, e.g. on component unmount
+off()
+```
+
+`persist()` uses the same path syntax as `observer()`.
+
+Nested paths such as `state.user.preferences.theme` are supported, provided the intermediate objects already exist in `state`.
+
+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