memorio 4.8.0 → 4.9.5

package/README.md

@@ -1,672 +1,377 @@
 # 🧠 memorio
 
-![banner](https://raw.githubusercontent.com/passariello/container/refs/heads/main/memorio/banner.svg)
-
-[![npm version](https://img.shields.io/npm/v/memorio.svg)](https://npmjs.com/package/memorio)
-[![npm downloads](https://img.shields.io/npm/dm/memorio.svg)](https://npmjs.com/package/memorio)
-[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18-gray?logo=node.js)](https://nodejs.org)
-![Browser](https://img.shields.io/badge/Browser-Chrome%20/%20Firefox%20/%20Safari-gray?logo=google-chrome)
-![Deno](https://img.shields.io/badge/Deno-compatible-gray?logo=deno)
-![Edge Workers](https://img.shields.io/badge/Edge%20Workers-compatible-gray)
-![TypeScript](https://img.shields.io/badge/TypeScript-native-gray?logo=typescript)
-![React](https://img.shields.io/badge/React-compatible-gray?logo=react)
-![Tests](https://img.shields.io/badge/tests-101%20passed-green)
-![License](https://img.shields.io/badge/License-MIT-gray)
-
-### One import. Global state, persistence, and a IndexedDB layer - done.
-
-```javascript
+**Local-first memory for JavaScript.**
+One import. Global state, local persistence, SQLite, semantic memory, optional sync.
+
+[![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)
+
+```ts
 import 'memorio'
 
-state.user = { name: 'Sara' }   // reactive, everywhere, instantly
+state.user = { name: 'Sara', role: 'admin' }
+state.counter++
 ```
 
-No provider tree. No reducers. No actions to dispatch before you can change a number. If you've ever set up a global store for an app that just needed *"a value, shared, that updates the UI when it changes,"* memorio is the toolkit for that thirty-second job - and it keeps growing with you: session storage, a cache, typed IndexedDB tables, an observer system, a React hook, devtools, and a change logger, all sharing one mental model.
+No provider tree. No reducers. No actions. No boilerplate.
+Just data that exists where your application needs it — and grows with it.
 
 ---
 
-## Table of Contents
-
-1. [Is this for you?](#is-this-for-you)
-2. [Installation](#installation)
-3. [Quick Start](#quick-start)
-4. [API Reference](#api-reference)
-5. [Typed Stores](#typed-stores)
-6. [Schema Validation](#schema-validation)
-7. [Cross-Platform Behavior](#cross-platform-behavior)
-8. [Context Isolation (multi-tenant)](#context-isolation-multi-tenant)
-9. [Security](#security)
-10. [License](#license)
+## Table of contents
+
+- [Why memorio](#why-memorio)
+- [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
+- [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)
+- [License](#license)
 
 ---
 
-## Is this for you?
-
-memorio is built for speed of thought: you think "I need this value everywhere," you write one line, it works. That's the entire pitch - and it's a real one, not a rewritten complaint about how much Redux boilerplate you've had to write.
+## Why memorio
 
-**Reach for memorio when:**
-- You want state that's simply *there* - no store setup, no provider wrapping your app.
-- You want `localStorage`, `sessionStorage`, and `IndexedDB` behind one consistent API instead of learning three.
-- You're prototyping, building an internal tool, or shipping something small-to-medium where iteration speed matters more than architectural ceremony.
+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.
 
-**Reach for something else when:**
-- You need every state path statically type-checked against every observer - memorio's `state.foo.bar` and `observer('state.foo.bar', ...)` are connected by a string, not by the compiler, so a rename won't be caught for you. However, if you want compiler-checked state access, use `memorio.typed<T>()` (see [Typed Stores](#typed-stores)) which gives you full static types on the global `state` proxy. For runtime validation as well, combine with `memorio.registerSchema()` (see [Schema Validation](#schema-validation)).
-- You need Redux-style middleware, action logs, or time-travel debugging as a hard requirement for a large team - those tools exist because that discipline solves real problems at scale, not because their authors enjoy boilerplate. Memorio logs through `memorio.logger` and inspects via `memorio.devtools`, but doesn't have Redux DevTools time-travel.
-- Your isolation requirements are a security boundary, not a convenience - see [Context Isolation](#context-isolation-multi-tenant) before you rely on it for that.
+memorio gives these concerns **one runtime and one mental model** — without forcing you to use all of it.
 
-Pick the right tool. memorio is at its best when the answer to "how much state architecture do I need here?" is genuinely "not much."
-
----
-
-## Installation
+| 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 |
+
+Start with `state`. Add the rest only when your app actually needs it.
+
+## Which layer should I use
+
+```text
+Does the UI need to react automatically to changes?
+│
+├─ Yes → state, or a memory-backed reactive slice
+│
+└─ 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)
+   │
+   ├─ Need relations, joins, SQL?          → sqlite
+   └─ Is this "knowledge" the app reasons
+      about (confidence, source, expiry)?  → memory
+```
+
+## Install
 
 ```bash
 npm i memorio
-# pnpm add memorio
-# yarn add memorio
-
-# Optional - only if you use the React hook
-npm i react react-dom
-
-# Optional - only if you want a local sql.js for `sqlite` (default uses CDN)
-npm i sql.js
 ```
 
----
+Optional peers, only loaded when used:
 
-## Quick Start
-
-### Global style - the whole point of memorio
-
-```typescript
-import 'memorio' // once, at your entry point
-
-state.user = { name: 'Sara', role: 'admin' }
-state.counter++
-
-useObserver(
-  () => console.debug('user changed:', state.user),
-  [state.user]
-)
-```
-
-### Named imports - same instances, explicit about it
-
-```typescript
-import { state, store, session, cache, idb, observer, useObserver, dispatch, memorio } from 'memorio'
-
-state.user = { name: 'Sara' }
-store.set('theme', 'dark')
-```
-
-```tsx
-function Counter() {
-  const [, forceUpdate] = useReducer(x => x + 1, 0)
-  useObserver(forceUpdate, [state.counter])
-  return <div>Count: {state.counter}</div>
-}
+```bash
+npm i react react-dom   # React integration
+npm i sql.js            # SQLite engine
 ```
 
-Two styles, one engine underneath - use whichever reads better in your codebase.
-
----
+**Zero production dependencies.** See [Security](#security).
 
-## API Reference
+## Quick start
 
-### `state` - reactive, volatile, Proxy-based
+```ts
+import 'memorio'
 
-```javascript
 state.user = { name: 'Sara', role: 'admin' }
 const name = state.user.name
+```
 
-state.list          // ['user', 'items', ...]
-state.remove('items')
-state.removeAll()
+Reactive, in-memory, Proxy-based, globally accessible. Lock a slice you don't want mutated by accident:
 
-// Freeze a slice of state when you need to stop guessing who mutated it
+```ts
 state.config = { maxUsers: 100 }
 state.config.lock()
-state.config.maxUsers = 200   // throws: state 'config' is locked
+state.config.maxUsers = 200   // throws
 state.config.unlock()
 ```
 
-### `store` - the value that survives a refresh
-
-```javascript
-store.set('preferences', { theme: 'dark' })
-store.get('preferences')      // { theme: 'dark' } or null
-store.isPersistent            // true when backed by real localStorage
-```
-
-### `session` - lives as long as the tab does
-
-```javascript
-session.set('token', 'user-abc-123')
-session.get('token')
-```
-
-### `cache` - the fastest thing you own, gone on refresh
-
-```javascript
-cache.set('temp', computeExpensiveResult())
-cache.get('temp')
-```
-
-### `idb` - typed, async, structured tables without the ceremony
-
-```javascript
-await idb.db.create('my-db')
-await idb.table.create('my-db', 'users')
-await idb.data.set('my-db', 'users', { id: 1, name: 'Sara' })
-const user = await idb.data.get('my-db', 'users', 1)
-```
-
-> IndexedDB is a browser-only primitive - see [Cross-Platform Behavior](#cross-platform-behavior) for what happens off the browser.
-
-### `sqlite` - in-memory SQLite, zero config
+Prefer explicit imports over the global? Same runtime either way:
 
-`memorio.sqlite` is an optional, lazily-loaded SQLite engine backed by [`sql.js`](https://sql.js.org) (the optional `sql.js` npm package is **not** a build-time dependency). It runs entirely in memory — ideal for ad-hoc SQL, structured queryable data, and local relational lookups. The engine is fetched on first use and never loaded when you don't touch `sqlite`.
-
-```javascript
-import 'memorio' // or: import { sqlite } from 'memorio'
-
-await sqlite.ready                          // waits until the sql.js engine is loaded (or rejected)
-sqlite.db.support()                         // true when the current platform can run sql.js
-```
-
-Bases (databases) are addressed by name, like `idb`:
-const SQL = await sqlite.db.getSQL()        // the underlying sql.js engine (loaded once, cached)
-sqlite.db.version()                         // engine version string, or null before load
-```
-
-Bases (databases) are addressed by name, like `idb`. `sqlite.db.create('app')` opens (or creates) an in-memory database, while `sqlite.db.get('app')` retrieves an already-open handle (`sqlite.db.list/delete/size` round out the lifecycle):
-
-```javascript
-await sqlite.db.create('app')    // in-memory database handle
-await sqlite.query.run('app', 'CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)')
-``` `sqlite.data` gives a small shortcut layer, and `sqlite.query` runs SQL:
-
-```javascript
-// Write (shortcut over raw prepare/bind)
-await sqlite.data.set('app', 'users', { id: 1, name: 'Sara' })
-await sqlite.data.get('app', 'users', 1)    // { id: 1, name: 'Sara' }
-
-// SQL
-await sqlite.query.run('app', 'CREATE TABLE items (id INTEGER PRIMARY KEY, name TEXT)')
-const rows = await sqlite.query.select('app', 'SELECT * FROM items', [1])
-
-// Portability: export / import a whole base as a binary blob
-const blob = await sqlite.db.export('app')
-await sqlite.db.import('app', blob)
-
-// Clean up
-await sqlite.db.delete('app')
-```
-
-#### Loading the engine
-
-The default loader injects the sql.js UMD build (`sql-wasm-browser.js`) from the
-jsDelivr CDN as a classic `<script>`; on load it exposes the `initSqlJs` factory
-on `globalThis`, which memorio then calls with your `locateFile`. This avoids a
-bare `import('sql.js')` so bundlers never resolve the optional `sql.js`
-dependency at build time:
-
-```javascript
-// Zero config: CDN <script> loader (default)
-await sqlite.ready
-```
-
-If you prefer a local/bundled `sql.js` (offline, private network, or to pin a
-version), install it and supply your own loader:
-
-```bash
-npm i sql.js    # optional peer
-```
-
-```javascript
-import { sqlite } from 'memorio'
-
-sqlite.config({ loader: () => import('sql.js') })   // local/npm build of sql.js
-await sqlite.ready
-```
-
-You can also point the WASM `locateFile` step at your own CDN/base via
-`sqliteWasmBase` on `globalThis`, or pass a custom `locateFile` through
-`sqlite.config({ locateFile })`:
-
-```javascript
-globalThis.sqliteWasmBase = 'https://your-cdn.example.com/sql.js/dist/'
-sqlite.config({ locateFile: (file) => `https://your-cdn.example.com/sql.js/dist/${file}` })
+```ts
+import { state, store, session, cache, idb, sqlite, memorio } from 'memorio'
 ```
 
-When the engine can't load (e.g. no WASM support), `sqlite.ready` rejects, `sqlite._disabled` becomes `true`, and `sqlite._warning` explains why — `db.support()` simply returns `false` so you can degrade gracefully.
-
-- `sqlite.config({ persistence: true })` / `sqlite.db.create('app', { persistence: true })` snapshot a database to `store` (localStorage, namespaced) and restore it on reopen — sql.js databases are in-memory by default; see [SQLite docs – Persistence & dev download](markdown/SQLITE.md#example-5-persistence--dev-download).
-
-See [SQLite docs](markdown/SQLITE.md) for the full reference.
+## Observing changes
 
-### `observer` / `useObserver` - watch a path, react to it
+Reactivity isn't a React add-on — it's built into the runtime. Watch any state path directly, in any environment:
 
-```javascript
-observer('state.user', (newVal, oldVal) => {
-  console.debug('user changed:', newVal, oldVal)
+```ts
+observer('state.user', (next, previous) => {
+  console.log('user changed:', next, previous)
 })
-```
 
-> Keys here are plain strings, not statically checked against `state`'s shape. Keep the observer near the code that shapes that state, and grep before you rename.
+// nested paths work too
+observer('state.user.name', callback)
+```
 
-### `dispatch` - the event bus underneath it all
+`dispatch` is the event mechanism underneath it, if you need to hook in lower-level:
 
-```javascript
-memorio.dispatch.listen('state.user', (event) => console.debug(event.detail))
+```ts
+memorio.dispatch.listen('state.user', event => console.debug(event.detail))
 memorio.dispatch.set('state.user', { detail: { name: 'Sara' } })
 ```
 
-### `devtools` - see everything, instantly
+`observer` paths are runtime strings — for compiler-checked access, see [typed state](#typed-state--schema-validation).
 
-```javascript
-memorio.devtools.inspect()
-memorio.devtools.stats()
-memorio.devtools.exportData()
-```
+React apps get a dedicated hook, `useObserver` — see [React integration](#react-integration).
 
-Pairs with [dphelper-manager](https://chrome.google.com/webstore/detail/dphelper-manager-dev-tool/oppppldaoknfddeikfloonnialijngbk) for visual, time-travel inspection of your global state straight from devtools.
+## The layers
 
-### `logger` - a black box for every change
+### `store` — persistent key/value
 
-```javascript
-memorio.logger.configure({ enabled: true, logToConsole: true })
-memorio.logger.getHistory()
+```ts
+store.set('preferences', { theme: 'dark' })
+const preferences = store.get('preferences')
 ```
 
-> It logs *everything* written to `state`/`store`/`session` - including anything sensitive you put there. Great for debugging, but don't leave it on unconditionally in production if secrets or PII pass through your state. See [Security](#security).
-
----
-
-## Typed Stores
-
-`memorio.typed<T>()` returns the global `state` proxy cast to a TypeScript type `T`, giving you **compile-time** type safety on every access and mutation. The returned object is the *exact same* Proxy as `globalThis.state` — no duplication, no overhead.
-
-```typescript
-import 'memorio'
-
-interface AppState {
-  user: { name: string; age: number; email: string }
-  theme: 'light' | 'dark'
-  items: string[]
-}
-
-const app = memorio.typed<AppState>()
-
-// Type-checked at compile time:
-app.user = { name: 'Sara', age: 30, email: 'sara@test.com' }
-app.theme = 'dark'
-
-// TypeScript errors:
-// app.user = { name: 42 }            // age missing, name wrong type
-// app.theme = 'purple'               // not a valid literal
-```
+Backed by `localStorage` in the browser (`store.isPersistent === true`); falls back to memory elsewhere.
 
-The same data is accessible via the global `state` proxy — `app` and `state` are identical instances:
+### `session` — follows the tab
 
-```typescript
-state.user = { name: 'Sara', age: 30, email: 'sara@test.com' }
-app.user.name   // 'Sara' — same Proxy
+```ts
+session.set('token', 'user-abc-123')
 ```
 
-For runtime safety (rejecting invalid values even when TypeScript isn't checking), combine with [Schema Validation](#schema-validation) below.
-
-See [Typed Stores docs](markdown/TYPED.md) for full examples.
-
----
-
-## Schema Validation
-
-`memorio.registerSchema(path, schema)` lets you register runtime validators for state paths. When a write to `state.somePath = value` violates a registered schema, the write is **rejected** before the value is stored.
+Backed by `sessionStorage`. Good for auth state, wizards, tab-scoped data.
 
-```typescript
-import 'memorio'
+### `cache` — volatile, fast
 
-memorio.registerSchema('user', {
-  type: 'object',
-  required: ['name', 'email'],
-  properties: {
-    name: { type: 'string', min: 1 },
-    email: { type: 'string', pattern: /^[^@]+@[^@]+$/ },
-    age: { type: 'number', min: 0, max: 150 }
-  }
-})
-
-state.user = { name: 'Sara', email: 'sara@test.com', age: 30 }  // accepted
-state.user = { name: 'Sara' }                                    // rejected: missing 'email'
-state.user = { name: 42 }                                        // rejected: wrong type
+```ts
+cache.set('expensive-result', computeExpensiveResult())
 ```
 
-Custom validator functions are also supported:
+Disappears when the runtime disappears. No persistence guarantee, ever.
 
-```typescript
-memorio.registerSchema('theme', (val) => {
-  return val === 'light' || val === 'dark'
-    ? true
-    : 'theme must be "light" or "dark"'
-})
+### `idb` — durable, structured
 
-state.theme = 'purple'  // rejected: "theme must be light or dark"
-state.theme = 'dark'    // accepted
+```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)
 ```
 
-Manual validation without writing:
+Check before relying on it in portable code: `memorio.getCapabilities()`.
 
-```typescript
-memorio.validate('user', { name: 'Sara', email: 'sara@test.com' })
-// { valid: true }
+### `sqlite` — a real local SQL engine
 
-memorio.validate('user', { name: 'Sara' })
-// { valid: false, errors: ["user: missing required property 'email'"] }
-```
+```ts
+await sqlite.ready
+await sqlite.db.create('app')
 
-Manage registered schemas:
+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'])
 
-```typescript
-memorio.listSchemas()           // ['user', 'theme']
-memorio.unregisterSchema('theme')  // removes the validator
+const admins = await sqlite.query.select('app', `SELECT * FROM users WHERE role = ?`, ['admin'])
 ```
 
-**Typed + Schema** — combine both for full safety:
+Runs **in memory by default**, powered by `sql.js` (lazy-loaded — see [loading strategies](#cross-platform-support)). Enable persistence explicitly when you need it:
 
-```typescript
-interface AppState {
-  user: { name: string; email: string }
-  theme: 'light' | 'dark'
-}
-
-const app = memorio.typed<AppState>()
-
-memorio.registerSchema('user', {
-  type: 'object',
-  required: ['name', 'email'],
-  properties: {
-    name: { type: 'string', min: 1 },
-    email: { type: 'string', pattern: /^[^@]+@[^@]+$/ }
-  }
-})
-
-app.user = { names: 'Sara' }        // ❌ TS: wrong shape
-app.user = { name: '', email: '' }  // ❌ TS passes, ❌ runtime: name too short
-app.user = { name: 'Sara', email: 'sara@test.com' } // ✅ both pass
+```ts
+await sqlite.db.create('app', { persistence: true })
 ```
 
-See [Schema Validation docs](markdown/SCHEMA.md) for the full schema definition reference.
-
----
-
-## Memory System
+> ⚠️ 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).
 
-`memorio.memory` provides a semantic memory layer — a key/value store with **type safety**, **TTL**, **confidence scoring**, **tagging**, and **scope-based persistence**. It's designed for AI agents and applications that need structured, queryable memory with lifecycle management.
+### `memory` — semantic application memory
 
-### Core API
+The layer that makes memorio more than a state manager. Structured memory with type, confidence, TTL, tags, source, scope, and a real lifecycle:
 
 ```ts
-// remember(key, value, options)
 await memorio.memory.remember('user.language', 'Italian', {
   type: 'preference',
   confidence: 0.92,
   scope: 'local',
-  ttl: null,           // never expires
-  tags: ['ui', 'user'],
-  source: 'conversation'
+  tags: ['user', 'ui'],
+  source: 'conversation',
 })
 
-// recall(key, options)
-const lang = await memorio.memory.recall('user.language')
-// → 'Italian'
-
-// update(key, value, options) — creates a superseded version of the old entry
-await memorio.memory.update('user.language', 'English', { confidence: 0.95 })
-
-// forget(key) — permanently deletes
-await memorio.memory.forget('user.language')
+const language = await memorio.memory.recall('user.language')
 ```
 
-### Scopes
+Updates don't overwrite — they **supersede**, preserving history:
 
-| Scope | Storage | TTL | Cross-session | Size limit |
-|---|---|---|---|---|
-| `hot` | `state` proxy | ✅ | ❌ | ~5MB (RAM) |
-| `session` | `sessionStorage` | ✅ | Tab only | ~5MB |
-| `local` | `localStorage` | ✅ | ✅ | ~10MB |
-| `durable` | `IndexedDB` | ✅ | ✅ | ~1GB+ |
-
-Default scope is `local` for values ≤100KB, `durable` for larger values.
+```ts
+await memorio.memory.update('user.language', 'English', { confidence: 0.95 })
+// old entry → status: 'superseded'   |   new entry → status: 'active'
+```
 
-### Context API
+Retrieve what's *relevant*, not everything:
 
 ```ts
-// context() — returns ranked, relevant memories
 const context = await memorio.memory.context({
   tags: 'user',
   types: ['preference', 'decision'],
   minConfidence: 0.7,
-  maxEntries: 10
+  maxEntries: 10,
 })
-// → [{ key, value, relevance, age, confidence, ... }]
 ```
 
-### Memory Entry Model
-
-Each memory is stored as a structured entry:
+> ℹ️ **"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.
 
-```ts
-{
-  id: string          // unique identifier
-  key: string         // path-like key (e.g. "user.preference.theme")
-  value: any          // the stored data
-  type: MemoryType    // 'fact' | 'preference' | 'decision' | 'task' | 'context'
-  confidence: number  // 0.0–1.0
-  scope: MemoryScope  // 'hot' | 'session' | 'local' | 'durable'
-  ttl?: number | null // milliseconds (null = never expires)
-  tags: string[]      // for filtering
-  source?: string     // where this memory came from
-  status: MemoryStatus // 'active' | 'obsolete' | 'superseded'
-  createdAt: number   // timestamp
-  lastConfirmedAt: number
-  supersededId?: string | null
-}
-```
+`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.
 
-### Memory Lifecycle
+## React integration
 
-| Operation | Behavior |
-|---|---|
-| `remember(key, newValue)` when entry exists | Old entry → `superseded` status, new entry → `active` |
-| `recall(key)` | Returns active value; expired entries return `null` unless `includeObsolete: true` |
-| `update(key, value)` | Creates superseded copy + updated active entry |
-| Entry with `ttl` expires | Status → `obsolete` (via `forgetExpired()`) |
-| `clear()` | Wipes all memories + index |
+React is an integration, not a requirement — `useObserver` is a thin bridge onto the same `observer` mechanism from above:
 
-See [Memory docs](markdown/MEMORY.md) for full reference.
+```tsx
+function Counter() {
+  const [, forceUpdate] = useReducer(x => x + 1, 0)
+  useObserver(forceUpdate, [state.counter])
+  return <div>{state.counter}</div>
+}
+```
 
----
+## Typed state & schema validation
 
-## Synchronization & Cloud (optional)
+TypeScript types for compile-time safety:
 
-`memorio.memory` is **local-first**. The 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.
+```ts
+interface AppState {
+  user: { name: string; age: number; email: string }
+  theme: 'light' | 'dark'
+}
 
-```
-                    memorio
-                       │
-              ┌────────┴────────┐
-              │   Memory Engine │
-              └────────┬────────┘
-          ┌────────────┼────────────┐
-          ▼            ▼            ▼
-        local      SQLite         cloud
-        memory     durable        sync
+const app = memorio.typed<AppState>()
+app.theme = 'dark'
+app.theme = 'purple'   // ❌ TypeScript error
 ```
 
-### Configuring a backend
+`app === state` — same Proxy, no duplicated store.
 
-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, a PostgreSQL
-database, etc.). **Memorio never handles credentials** — authentication and
-authorization live in your backend/provider (OWASP A01: Broken Access Control):
+Runtime validation for values crossing trust boundaries:
 
 ```ts
-memorio.memory.configure({
-  namespace: 'user:123:device:abc',   // tenant/user/device — partitions the journal
-  provider: {                          // application-owned transport
-    push(ops) { return fetch('/api/sync', { method: 'POST', body: JSON.stringify(ops), headers: auth }) }
-    pull(since) { return fetch(`/api/sync?since=${since}`).then(r => r.json()) }
+memorio.registerSchema('user', {
+  type: 'object',
+  required: ['name', 'email'],
+  properties: {
+    name: { type: 'string', min: 1 },
+    email: { type: 'string', pattern: /^[^@]+@[^@]+$/ },
   },
-  auto: true                           // auto-replay pending ops on focus/online (default true)
 })
 
-await memorio.memory.ready   // waits until the local journal substrate is chosen
+state.user = { name: 'Sara' }   // rejected — missing required "email"
 ```
 
-Once configured, `memorio.memory` records every operation locally and keeps it
-until the provider acknowledges it.
+## Local-first sync
 
-### The local journal
+The local application owns its data; the cloud is optional transport.
 
-Every mutation (`remember`, `update`, `forget`, `expire`, `confirm`, `supersede`)
-is written to a local, **namespaced** operation journal:
+memorio syncs **operations** (`remember`, `update`, `forget`, `expire`, `confirm`, `supersede`), not database dumps, via a local journal that survives network failure:
 
 ```ts
-await memory.remember('user.language', 'Italian', { scope: 'local' })
-
-memory.journal.pending()      // -> [{ id, key:'user.language', value:'Italian', operation:'remember', sync:'pending', version: 1, updatedAt: ... }]
-memory.journal.markSynced([id])
-memory.journal.replay()       // pushes pending() to provider.provider, marks synced, optional pull+apply
-memory.journal.status()       // 'sqlite' | 'store'  (substrate in use)
+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()),
+  },
+  auto: true,
+})
 ```
 
-The journal stores the full entry plus `operation`, `version`, `updatedAt` and
-`sync` status, so conflicts can be resolved when connectivity returns.
-
-### Substrates
-
-The journal is persisted on `store` (localStorage / in-memory Map fallback) — **not** on a sql.js database, because sql.js databases are volatile (in-memory) and would lose pending operations on reload:
-
-| Substrate | Used for | Notes |
-|---|---|---|
-| `store` (localStorage) | sync journal | persistent across reloads; namespaced; Map fallback in Node |
-| `sqlite` (sql.js) | ad-hoc SQL / value storage | in-memory by default — use `persistence: true` to snapshot to `store` |
-| `idb` (IndexedDB) | `memorio.memory` durable scope values | persistent; persistent across reloads |
-
-The `sqlite.db.download(name)` dev helper also triggers a browser `.sqlite` download of an in-memory database on demand.
-
-### Sync = operations, not database dumps
-
-Memorio syncronizza **operazioni di memoria**, never a raw database dump. When
-two devices diverge, conflict resolution is based on `confidence`,
-`lastConfirmedAt`, `source`, `version` and `scope` — not just "last write wins":
+Conflict resolution defaults to *higher confidence wins, then more recent `lastConfirmedAt`* — override it when you need a different rule:
 
 ```ts
-// Device A: user.language = Italian, confidence 0.92
-// Device B: user.language = English, confidence 0.61
-// → the higher-confidence entry wins locally; the provider decides for shared.
-```
-
-The `namespace` (tenant / user / device) is the single partition key: local
-journal reads and writes are scoped to it, and they can never cross namespaces —
-a client holding a fake/forged namespace simply sees its own empty journal.
-
-### Scopes (isolation, not a security boundary)
-
-```
-scope: 'device'   // only this browser/device
-scope: 'user'      // follows the user across devices (via sync)
-scope: 'shared'   // shared across users/tenant
+memorio.memory.configure({
+  resolveConflict(local, remote) {
+    if (remote.source === 'user-correction') return remote
+    return local.confidence >= remote.confidence ? local : remote
+  },
+})
 ```
 
-`scope: 'user'`/`'shared'` require a provider + namespace. `scope: 'device'`
-is local only. As with `memorio.createContext`, **scoping is a naming convention,
-not a security boundary** — enforce real isolation in your backend.
-
-### Security posture
-
-- **NIST SP 800-53 / OWASP**: no credentials, tokens, or secrets are read from or
-  stored by `memorio`; sensitive state you place in `state`/`store`/`session`/`idb`
-  is not encrypted by memorio (see [Security](#security)).
-- **Namespace isolation**: journal reads/writes are keyed by
-  `namespace:id` at the storage layer; there is no API to enumerate or open
-  another namespace's journal (defense-in-depth).
-- **No dynamic code**: journal entries are strictly JSON-round-tripped and
-  size-capped (10 MB/entry); no `eval`/template-injection of provider data.
-- **Trust boundary**: the provider/backend owns authentication, authorization,
-  and remote-side conflict resolution. Memorio owns the local durable copy and
-  the operation log; it surfaces `conflict`/`error` rows via `journal.pending()`.
-- **NSA/CISA advice (data-at-rest/secrets)**: if you persist `state`/`store`
-  server-side or ship user data through your backend, encrypt it server-side with
-  keys you manage; memorio treats the local journal as untrusted-from-the-browser
-  and does not attest its own integrity.
-
-See [SQLite docs](markdown/SQLITE.md), [Memory docs](markdown/MEMORY.md), and the [Synchronization & Cloud guide](markdown/SYNC.md).
-
----
-
-## Cross-Platform Behavior
+This resolver only settles *client-side* divergence between what memorio has seen locally — the provider is still responsible for the final server-side policy.
 
-memorio runs everywhere JavaScript does - but "everywhere" means different guarantees in different places, and we'd rather tell you now than have you find out at 2am:
+## Cross-platform support
 
 | API | Browser | Node.js | Deno | Edge / Workers |
-|---|---|---|---|---|
-| `state` | Proxy in memory | Proxy in memory | Proxy in memory | Proxy in memory |
-| `observer` / `useObserver` | ✅ | ✅ | ✅ | ✅ |
-| `cache` | ✅ in memory | ✅ in memory | ✅ in memory | ✅ in memory |
-| `store` | `localStorage` | `Map` fallback - **not durable across restarts** | `Map` fallback - not durable | `localStorage` where available, else `Map` |
-| `session` | `sessionStorage` | `Map` fallback - not durable | `Map` fallback - not durable | `sessionStorage` where available, else `Map` |
-| `idb` | ✅ `IndexedDB` | ❌ not available | ❌ not available | ⚠️ check `getCapabilities()` |
-| `sqlite` | ✅ `sql.js` (lazy, CDN by default) | ❌ not available | ❌ not available | ⚠️ check `sqlite.db.support()` |
-| `devtools` | ✅ | ❌ | ❌ | ⚠️ |
-
-Same API top to bottom - that's the promise. But if your server code leans on `store.get(...)` surviving a redeploy, know that on Node/Deno it won't; the fallback is an in-memory cache with the same shape, not durable storage.
-
-```javascript
-memorio.isBrowser()
-memorio.isNode()
-memorio.isDeno()
-memorio.isEdge()
+|---|---:|---:|---:|---:|
+| `state` / `observer` / `cache` | ✅ | ✅ | ✅ | ✅ |
+| `store` / `session` | persistent | memory fallback | memory fallback | capability-dependent |
+| `idb` | ✅ | ❌ | ❌ | capability-dependent |
+| `sqlite` | ✅ | ❌ | ❌ | capability-dependent |
+| `devtools` | ✅ (dev-only) | ❌ | ❌ | capability-dependent |
 
+```ts
 memorio.getCapabilities()
-// { platform: 'browser', hasLocalStorage: true, hasIndexedDB: true, ... }
+memorio.isBrowser() / isNode() / isDeno() / isEdge()
 ```
 
-Check `getCapabilities()` before leaning on `idb` or persistent `store`/`session` in code that might run on more than one platform.
-
----
-
-## Context Isolation (multi-tenant)
+## Security
 
-```javascript
-const ctx = memorio.createContext('tenant-123')
+- Zero production dependencies — [verified 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
 
-ctx.state.user = { name: 'Isolated' }
-ctx.store.set('settings', { theme: 'dark' })
+**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.
 
-console.debug(state.user) // undefined - separate namespace
-```
+**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.
 
-Handy for keeping per-tenant or per-request state from colliding in the same process. Under the hood it's a key prefix (`tenant-123-key`) inside the same storage - a naming convention, not a hard memory boundary. Great for a browser tab; if you're running this in a shared Node.js process or an edge isolate that might be reused across requests, make sure tenant IDs can't collide or be forged, and don't treat this as your only isolation layer if the stakes are real.
+## Honest limitations
 
----
+We'd rather tell you where the edges are than have you find them in production.
 
-## Security
+- **`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.
 
-- Zero production dependencies.
-- No `eval`, no dynamic code execution, no bundled telemetry.
-- Session IDs generated via `crypto.randomUUID`.
-- Inputs validated, keys sanitized, errors caught at module boundaries.
+## When to use something else
 
-memorio does **not** encrypt what you put into `store`, `session`, or `idb` - they're thin, fast wrappers over `localStorage`/`sessionStorage`/`IndexedDB`, which store data in the clear on the user's device. Bring your own encryption layer for tokens, secrets, or regulated personal data.
+- **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.
 
-We build with recognized engineering guidance (NIST SP 800-53 practices) as an input to how we write code - that's a design discipline, not a compliance certificate, and no third-party audit has been performed. Found an issue? Report it privately - see `SECURITY.md` - rather than opening a public issue.
+## 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**:
+   ```ts
+   import 'memorio'
+   state.value = 42
+   ```
 
 ## License
 
-MIT © [Dario Passariello](https://dario.passariello.ca)
+MIT © Dario Passariello