memorio 4.7.3 → 4.9.5

package/README.md

@@ -1,466 +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.
-
-**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.
-
-**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.
-
-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."
-
----
+## 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.
+
+memorio gives these concerns **one runtime and one mental model** — without forcing you to use all of it.
+
+| 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
+```
 
-## Installation
+## 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 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
+Prefer explicit imports over the global? Same runtime either way:
 
-```javascript
-store.set('preferences', { theme: 'dark' })
-store.get('preferences')      // { theme: 'dark' } or null
-store.isPersistent            // true when backed by real localStorage
+```ts
+import { state, store, session, cache, idb, sqlite, memorio } from 'memorio'
 ```
 
-### `session` - lives as long as the tab does
+## Observing changes
 
-```javascript
-session.set('token', 'user-abc-123')
-session.get('token')
-```
+Reactivity isn't a React add-on — it's built into the runtime. Watch any state path directly, in any environment:
 
-### `cache` - the fastest thing you own, gone on refresh
+```ts
+observer('state.user', (next, previous) => {
+  console.log('user changed:', next, previous)
+})
 
-```javascript
-cache.set('temp', computeExpensiveResult())
-cache.get('temp')
+// nested paths work too
+observer('state.user.name', callback)
 ```
 
-### `idb` - typed, async, structured tables without the ceremony
+`dispatch` is the event mechanism underneath it, if you need to hook in lower-level:
 
-```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)
+```ts
+memorio.dispatch.listen('state.user', event => console.debug(event.detail))
+memorio.dispatch.set('state.user', { detail: { name: 'Sara' } })
 ```
 
-> IndexedDB is a browser-only primitive - see [Cross-Platform Behavior](#cross-platform-behavior) for what happens off the browser.
+`observer` paths are runtime strings — for compiler-checked access, see [typed state](#typed-state--schema-validation).
 
-### `observer` / `useObserver` - watch a path, react to it
+React apps get a dedicated hook, `useObserver` — see [React integration](#react-integration).
 
-```javascript
-observer('state.user', (newVal, oldVal) => {
-  console.debug('user changed:', newVal, oldVal)
-})
-```
-
-> 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.
+## The layers
 
-### `dispatch` - the event bus underneath it all
+### `store` — persistent key/value
 
-```javascript
-memorio.dispatch.listen('state.user', (event) => console.debug(event.detail))
-memorio.dispatch.set('state.user', { detail: { name: 'Sara' } })
+```ts
+store.set('preferences', { theme: 'dark' })
+const preferences = store.get('preferences')
 ```
 
-### `devtools` - see everything, instantly
+Backed by `localStorage` in the browser (`store.isPersistent === true`); falls back to memory elsewhere.
+
+### `session` — follows the tab
 
-```javascript
-memorio.devtools.inspect()
-memorio.devtools.stats()
-memorio.devtools.exportData()
+```ts
+session.set('token', 'user-abc-123')
 ```
 
-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.
+Backed by `sessionStorage`. Good for auth state, wizards, tab-scoped data.
 
-### `logger` - a black box for every change
+### `cache` — volatile, fast
 
-```javascript
-memorio.logger.configure({ enabled: true, logToConsole: true })
-memorio.logger.getHistory()
+```ts
+cache.set('expensive-result', computeExpensiveResult())
 ```
 
-> 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).
+Disappears when the runtime disappears. No persistence guarantee, ever.
 
----
+### `idb` — durable, structured
 
-## Typed Stores
+```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)
+```
 
-`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.
+Check before relying on it in portable code: `memorio.getCapabilities()`.
 
-```typescript
-import 'memorio'
-
-interface AppState {
-  user: { name: string; age: number; email: string }
-  theme: 'light' | 'dark'
-  items: string[]
-}
+### `sqlite` — a real local SQL engine
 
-const app = memorio.typed<AppState>()
+```ts
+await sqlite.ready
+await sqlite.db.create('app')
 
-// Type-checked at compile time:
-app.user = { name: 'Sara', age: 30, email: 'sara@test.com' }
-app.theme = 'dark'
+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 errors:
-// app.user = { name: 42 }            // age missing, name wrong type
-// app.theme = 'purple'               // not a valid literal
+const admins = await sqlite.query.select('app', `SELECT * FROM users WHERE role = ?`, ['admin'])
 ```
 
-The same data is accessible via the global `state` proxy — `app` and `state` are identical instances:
+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
-state.user = { name: 'Sara', age: 30, email: 'sara@test.com' }
-app.user.name   // 'Sara' — same Proxy
+```ts
+await sqlite.db.create('app', { persistence: true })
 ```
 
-For runtime safety (rejecting invalid values even when TypeScript isn't checking), combine with [Schema Validation](#schema-validation) below.
+> ⚠️ 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).
 
-See [Typed Stores docs](markdown/TYPED.md) for full examples.
+### `memory` — semantic application memory
 
----
-
-## Schema Validation
+The layer that makes memorio more than a state manager. Structured memory with type, confidence, TTL, tags, source, scope, and a real lifecycle:
 
-`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.
+```ts
+await memorio.memory.remember('user.language', 'Italian', {
+  type: 'preference',
+  confidence: 0.92,
+  scope: 'local',
+  tags: ['user', 'ui'],
+  source: 'conversation',
+})
 
-```typescript
-import 'memorio'
+const language = await memorio.memory.recall('user.language')
+```
 
-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 }
-  }
-})
+Updates don't overwrite — they **supersede**, preserving history:
 
-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
+await memorio.memory.update('user.language', 'English', { confidence: 0.95 })
+// old entry → status: 'superseded'   |   new entry → status: 'active'
 ```
 
-Custom validator functions are also supported:
+Retrieve what's *relevant*, not everything:
 
-```typescript
-memorio.registerSchema('theme', (val) => {
-  return val === 'light' || val === 'dark'
-    ? true
-    : 'theme must be "light" or "dark"'
+```ts
+const context = await memorio.memory.context({
+  tags: 'user',
+  types: ['preference', 'decision'],
+  minConfidence: 0.7,
+  maxEntries: 10,
 })
-
-state.theme = 'purple'  // rejected: "theme must be light or dark"
-state.theme = 'dark'    // accepted
 ```
 
-Manual validation without writing:
+> ℹ️ **"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.
 
-```typescript
-memorio.validate('user', { name: 'Sara', email: 'sara@test.com' })
-// { valid: true }
+`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.
 
-memorio.validate('user', { name: 'Sara' })
-// { valid: false, errors: ["user: missing required property 'email'"] }
-```
+## React integration
 
-Manage registered schemas:
+React is an integration, not a requirement — `useObserver` is a thin bridge onto the same `observer` mechanism from above:
 
-```typescript
-memorio.listSchemas()           // ['user', 'theme']
-memorio.unregisterSchema('theme')  // removes the validator
+```tsx
+function Counter() {
+  const [, forceUpdate] = useReducer(x => x + 1, 0)
+  useObserver(forceUpdate, [state.counter])
+  return <div>{state.counter}</div>
+}
 ```
 
-**Typed + Schema** — combine both for full safety:
+## Typed state & schema validation
+
+TypeScript types for compile-time safety:
 
-```typescript
+```ts
 interface AppState {
-  user: { name: string; email: string }
+  user: { name: string; age: number; email: string }
   theme: 'light' | 'dark'
 }
 
 const app = memorio.typed<AppState>()
+app.theme = 'dark'
+app.theme = 'purple'   // ❌ TypeScript error
+```
+
+`app === state` — same Proxy, no duplicated store.
 
+Runtime validation for values crossing trust boundaries:
+
+```ts
 memorio.registerSchema('user', {
   type: 'object',
   required: ['name', 'email'],
   properties: {
     name: { type: 'string', min: 1 },
-    email: { type: 'string', pattern: /^[^@]+@[^@]+$/ }
-  }
+    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
+state.user = { name: 'Sara' }   // rejected — missing required "email"
 ```
 
-See [Schema Validation docs](markdown/SCHEMA.md) for the full schema definition reference.
-
----
-
-## Memory System
+## Local-first sync
 
-`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.
+The local application owns its data; the cloud is optional transport.
 
-### Core API
+memorio syncs **operations** (`remember`, `update`, `forget`, `expire`, `confirm`, `supersede`), not database dumps, via a local journal that survives network failure:
 
 ```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'
+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,
 })
-
-// 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')
 ```
 
-### Scopes
-
-| 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.
-
-### Context API
+Conflict resolution defaults to *higher confidence wins, then more recent `lastConfirmedAt`* — override it when you need a different rule:
 
 ```ts
-// context() — returns ranked, relevant memories
-const context = await memorio.memory.context({
-  tags: 'user',
-  types: ['preference', 'decision'],
-  minConfidence: 0.7,
-  maxEntries: 10
+memorio.memory.configure({
+  resolveConflict(local, remote) {
+    if (remote.source === 'user-correction') return remote
+    return local.confidence >= remote.confidence ? local : remote
+  },
 })
-// → [{ key, value, relevance, age, confidence, ... }]
 ```
 
-### Memory Entry Model
+This resolver only settles *client-side* divergence between what memorio has seen locally — the provider is still responsible for the final server-side policy.
 
-Each memory is stored as a structured entry:
-
-```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
-}
-```
-
-### Memory Lifecycle
-
-| 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 |
-
-See [Memory docs](markdown/MEMORY.md) for full reference.
-
----
-
-## Cross-Platform Behavior
-
-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()` |
-| `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.
+## Security
 
----
+- 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
 
-## Context Isolation (multi-tenant)
+**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.
 
-```javascript
-const ctx = memorio.createContext('tenant-123')
+**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.
 
-ctx.state.user = { name: 'Isolated' }
-ctx.store.set('settings', { theme: 'dark' })
+## Honest limitations
 
-console.debug(state.user) // undefined - separate namespace
-```
+We'd rather tell you where the edges are than have you find them in production.
 
-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.
+- **`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.
 
----
+## When to use something else
 
-## Security
-
-- 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.
+- **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 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.
+## Design philosophy
 
-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.
-
----
+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