memorio 4.9.35 → 5.1.0

package/README.md

@@ -1,115 +1,39 @@
 # 🧠 memorio
 
-**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)
+**The memory layer for AI agents and apps — owned by the user, not the vendor.**
 
 ```ts
-import 'memorio'
+import 'memorio/global'
 
 state.user = { name: 'Sara', role: 'admin' }
 state.counter++
+
+console.log(state.user.name)
+console.log(state.counter)
 ```
 
 No provider tree. No reducers. No actions. No boilerplate.
 Just data, available where your application needs it.
 
-**And if you don't want a global API, don't use one:**
-
-```ts
-import { state, store, session, cache, idb, sqlite, memorio } from 'memorio'
-```
-
-The global API is a **choice**, not an architectural requirement.
-
----
-
-## Table of contents
-
-- [Why memorio](#why-memorio)
-- [Global is optional](#global-is-optional)
-- [Before / After](#before--after)
-- [Which layer should I use](#which-layer-should-i-use)
-- [Install](#install)
-- [Quick start](#quick-start)
-- [Observing changes](#observing-changes)
-- [The layers](#the-layers) — store · session · cache · idb · sqlite · memory
-- [Redux and other state managers](#redux-and-other-state-managers)
-  - [memorio vs Redux, at a glance](#memorio-vs-redux-at-a-glance)
-- [React integration](#react-integration)
-- [Typed state & schema validation](#typed-state--schema-validation)
-- [Local-first sync](#local-first-sync)
-- [Cross-platform support](#cross-platform-support)
-- [Security](#security)
-- [Honest limitations](#honest-limitations)
-- [When to use something else](#when-to-use-something-else)
-- [Design philosophy](#design-philosophy)
-- [A mental model](#a-mental-model)
-- [Recipes](#recipes)
-- [License](#license)
-
 ---
 
 ## Why memorio
 
-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 brings these concerns into **one runtime and one consistent model**, while keeping each layer independent.
+Most AI-powered apps (and most apps in general) eventually need more than "just state": reactive values, persistent data, session data, caches, structured browser storage, local SQL, application memory, history, and optional sync.
 
-| 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
+Usually that means a different library — and a different mental model — for each. Memorio gives them one consistent runtime, without making the simple case complicated:
 
 ```ts
-import 'memorio'
-state.user = { name: 'Sara' }
+state.value = 42
 ```
 
-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:
+But the reason memorio exists isn't just "fewer dependencies." It's this: **the memory an AI agent builds about a user shouldn't be locked inside a vendor's server, opaque, and impossible to inspect or move.** Memorio's memory layer is structured, inspectable, editable, and — when you turn on encryption — readable only with a key the vendor doesn't hold. It runs client-side, in the browser, on the edge, or in Node.
 
-```ts
-import { state } from 'memorio'
-state.user = { name: 'Sara' }
-```
+That said, this covers *structured* memory - preferences, decisions, facts with confidence and provenance - not semantic similarity search. If your agent needs "find things like this conversation," pair memorio with a dedicated vector store; see [`markdown/MEMORY.md`](./markdown/MEMORY.md).
 
-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
-│
-└─ No
-   │
-   ├─ Only while the runtime exists?          → cache
-   ├─ Only for this browser tab/session?      → session
-   ├─ Small persistent key/value data?        → store
-   ├─ Larger or structured browser data?      → idb
-   ├─ Relations, joins, or SQL?               → sqlite
-   └─ Knowledge the application should
-      remember (confidence, source, expiry)?  → memory
-```
+Add persistence, memory, history, or sync only when your application actually needs them. The common case stays tiny; the runtime grows with you.
+
+---
 
 ## Install
 
@@ -117,466 +41,121 @@ Does the UI need to react automatically to changes?
 npm install memorio
 ```
 
-Optional peers, only loaded when used:
-
-```bash
-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')
-```
-
-Same result, one reactive line instead of two effects and manual JSON serialization.
-
-## Quick start
-
-```ts
-import 'memorio'
+Zero production dependencies in core. Optional integrations (`react`, `sql.js`, etc.) are installed only when you use them.
 
-state.user = { name: 'Sara', role: 'admin' }
-state.counter++
-
-console.log(state.user.name)
-console.log(state.counter)
-```
+---
 
-Reactive, Proxy-based state. No provider tree to configure, no reducer to maintain.
+## Start here
 
-Lock a slice you don't want mutated by accident:
+Three things cover most apps - reactive state, persistence, and observation:
 
 ```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:
+import { state, persist, observer } from 'memorio'
 
-```ts
-import { state, store, session, cache, idb, sqlite, memorio } from 'memorio'
-```
-
-## Observing changes
+state.user = { name: 'Sara' }
 
-Reactivity is part of the runtime — it is not tied to React.
+persist('state.user')
 
-```ts
-observer('state.user', (next, previous) => {
-  console.log('user changed:', next, previous)
+observer('state.user', user => {
+  console.log(user)
 })
-
-// nested paths work too
-observer('state.user.name', callback)
 ```
 
-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
-```
-
-Each subscription owns its own unsubscribe function. Prefer the returned `off()` over `memorio.dispatch.remove('state.user')`, which removes **all** listeners registered under that name.
-
-React apps get a dedicated hook, `useObserver` — see [React integration](#react-integration).
-
-## The layers
-
-### `store` — persistent key/value data
+And this is what makes memorio a *memory* layer, not just a state manager - structured, inspectable facts about a user or agent, not just ephemeral UI state:
 
 ```ts
-store.set('preferences', { theme: 'dark' })
-const preferences = store.get('preferences')
-```
-
-Backed by `localStorage` in the browser. Falls back to memory in environments without persistent storage — check `store.isPersistent` when portability matters.
-
-### `session` — data for the current session
-
-```ts
-session.set('wizard-step', 3)
-const step = session.get('wizard-step')
-```
-
-Backed by `sessionStorage`. Good for multi-step workflows, temporary preferences, tab-scoped data.
-
-### `cache` — volatile runtime data
-
-```ts
-cache.set('expensive-result', computeExpensiveResult())
-```
-
-Disappears when the runtime disappears. No persistence guarantee, ever.
+import { memorio } from 'memorio'
 
-### `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 runtime support before depending on it: `memorio.getCapabilities()`.
-
-### `sqlite` — local SQL
-
-```ts
-await sqlite.ready
-await sqlite.db.create('app')
-
-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'])
-
-const admins = await sqlite.query.select('app', `SELECT * FROM users WHERE role = ?`, ['admin'])
-```
-
-Runs **in memory by default**, using `sql.js`. Persistence is explicit:
-
-```ts
-await sqlite.db.create('app', { persistence: true })
-```
-
-> ⚠️ **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` — application memory
-
-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', {
   type: 'preference',
   confidence: 0.92,
-  scope: 'local',
-  tags: ['user', 'ui'],
-  source: 'conversation',
+  source: 'conversation'
 })
 
 const language = await memorio.memory.recall('user.language')
+// { value: 'Italian', confidence: 0.92, source: 'conversation', ... }
 ```
 
-Updates don't overwrite — they supersede, preserving history:
-
-```ts
-await memorio.memory.update('user.language', 'English', { confidence: 0.95 })
-// previous entry → status: 'superseded'   |   new entry → status: 'active'
-```
-
-Retrieve what's relevant to the current operation, not everything:
+For most apps, that's enough. Everything below is an optional capability you can add when your application needs it - each one documented in its own reference file.
 
-```ts
-const context = await memorio.memory.context({
-  tags: 'user',
-  types: ['preference', 'decision'],
-  minConfidence: 0.7,
-  maxEntries: 10,
-})
-```
-
-The context system considers tags, type, confidence, and recency.
-
-> ℹ️ **"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` connects to the same observer system described above.
-
-```tsx
-function Counter() {
-  const [, forceUpdate] = useReducer(x => x + 1, 0)
-  useObserver(forceUpdate, [state.counter])
-  return <div>{state.counter}</div>
-}
-```
-
-The runtime itself remains independent of React.
-
-## Typed state & schema validation
-
-TypeScript types give compile-time guarantees without creating another state container:
-
-```ts
-interface AppState {
-  user: { name: string; age: number; email: string }
-  theme: 'light' | 'dark'
-}
-
-const app = memorio.typed<AppState>()
-app.theme = 'dark'
-app.theme = 'purple'   // TypeScript error
-```
-
-`app === state` — same proxy, no duplicated store.
-
-Runtime validation protects values crossing trust boundaries:
-
-```ts
-memorio.registerSchema('user', {
-  type: 'object',
-  required: ['name', 'email'],
-  properties: {
-    name: { type: 'string', min: 1 },
-    email: { type: 'string', pattern: /^[^@]+@[^@]+$/ },
-  },
-})
-
-state.user = { name: 'Sara' }   // rejected: missing required "email"
-```
-
-Arrays validate each element via `items`:
-
-```ts
-memorio.registerSchema('tags', { type: 'array', items: { type: 'string' } })
-
-state.tags = ['a', 'b']   // accepted
-state.tags = [1, 2, 3]    // rejected
-```
-
-## Local-first sync
-
-The local application owns its data — the cloud is optional transport. memorio synchronizes **operations** (`remember`, `update`, `forget`, `expire`, `confirm`, `supersede`), not database dumps. A local journal records operations so temporary network failures don't stop the application from working.
-
-```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()),
-  },
-  auto: true,
-})
-```
-
-```text
-local application → memorio memory → local journal → offline / cloud
-```
-
-The network is an extension of the local application, not its prerequisite.
-
-Remote operations are ordered causally using HLC timestamps. For concurrent writes to the same key, memorio provides a deterministic default — a custom resolver can override it:
-
-```ts
-memorio.memory.configure({
-  resolveConflict(local, remote) {
-    if (remote.source === 'user-correction') return remote
-    return local.confidence >= remote.confidence ? local : remote
-  },
-})
-```
-
-Without a resolver, the default policy applies the remote entry on a tie. The resolver operates client-side — the sync provider is still responsible for any final server-side conflict policy.
-
-## 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 |
-
-```ts
-memorio.getCapabilities()
-memorio.isBrowser() / memorio.isNode() / memorio.isDeno() / memorio.isEdge()
-```
-
-Do not assume every persistence backend exists in every runtime.
-
-## Security
-
-- Zero production dependencies — [checked by Socket.dev](https://socket.dev/npm/package/memorio) and [scanned by Snyk](https://snyk.io/test/npm/memorio)
-- No `eval`, no dynamic code execution, no bundled telemetry
-- Sanitized keys, validated inputs, caught module-boundary errors
-- Bounded journal entries, UUID-based session identifiers
-
-> ⚠️ **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 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
+---
 
-memorio deliberately documents its edges.
+## Where to go next
+
+### Core
+| Topic | Reference |
+| --- | --- |
+| Reactive state | [`markdown/STATE.md`](./markdown/STATE.md) |
+| Persistent key/value store | [`markdown/STORE.md`](./markdown/STORE.md) |
+| Observing changes | [`markdown/OBSERVER.md`](./markdown/OBSERVER.md) |
+| Structured application memory | [`markdown/MEMORY.md`](./markdown/MEMORY.md) |
+
+### Storage
+| Topic | Reference |
+| --- | --- |
+| Session storage (tab-scoped) | [`markdown/SESSION.md`](./markdown/SESSION.md) |
+| In-memory cache | [`markdown/CACHE.md`](./markdown/CACHE.md) |
+| IndexedDB | [`markdown/IDB.md`](./markdown/IDB.md) |
+| SQLite (`sql.js` / `bun:sqlite`) | [`markdown/SQLITE.md`](./markdown/SQLITE.md) |
+
+### Sync & history
+| Topic | Reference |
+| --- | --- |
+| Local-first sync & cloud | [`markdown/SYNC.md`](./markdown/SYNC.md) |
+| Memory attachments (linking memory entries) | [`markdown/MEMORY-ATTACHMENT.md`](./markdown/MEMORY-ATTACHMENT.md) |
+| History, undo/redo, snapshot, diff, trace | [`markdown/HISTORY.md`](./markdown/HISTORY.md) |
+
+### Integrations
+| Topic | Reference |
+| --- | --- |
+| React (`useObserver`) | [`markdown/USEOBSERVER.md`](./markdown/USEOBSERVER.md) |
+| Redux bridge | [`markdown/REDUX.md`](./markdown/REDUX.md) |
+| Typed state | [`markdown/TYPED.md`](./markdown/TYPED.md) |
+| Schema validation | [`markdown/SCHEMA.md`](./markdown/SCHEMA.md) |
+| Pub/sub events outside React | [`markdown/DISPATCH.md`](./markdown/DISPATCH.md) |
+| Console logging middleware | [`markdown/LOGGER.md`](./markdown/LOGGER.md) |
+
+### Ops & security
+| Topic | Reference |
+| --- | --- |
+| Platform detection & multi-tenant context isolation | [`markdown/PLATFORM.md`](./markdown/PLATFORM.md) |
+| Classic `import` vs `memorio/global` | [`markdown/IMPORT.md`](./markdown/IMPORT.md) |
+| Runtime introspection | [`markdown/INSPECT.md`](./markdown/INSPECT.md) |
+| Browser DevTools | [`markdown/DEVTOOLS.md`](./markdown/DEVTOOLS.md) |
+| Security, encryption, threat model | [`SECURITY.md`](./SECURITY.md) |
+| Internal self-assessment *(not a third-party audit)* | [`markdown/SELF-ASSESSMENT.md`](./markdown/SELF-ASSESSMENT.md) |
+
+### Other
+| Topic | Reference |
+| --- | --- |
+| Version history | [`CHANGELOG.md`](./CHANGELOG.md) |
+| Working examples - each file has a `Run:` comment at the top (typically `npx ts-node examples/<name>.ts`, or `npx ts-node --esm examples/<name>.tsx` for React examples) | [`examples/`](./examples/) |
+| Architecture decisions | [`adr/`](./adr/) |
 
-- **Semantic memory is structured, not vector-based.** `memory.context()` uses structured ranking, not embedding similarity search.
-- **SQLite persistence is not incremental** — the current strategy serializes the complete database on flush; large datasets need deliberate batching.
-- **Contexts and namespaces are not authorization** — they organize application data, they don't replace authentication or backend authorization.
-- **Data is not encrypted automatically** — memorio doesn't pretend local persistence is secure storage.
-- **DevTools are runtime-controlled, not build-removed** — production builds should still configure `NODE_ENV` correctly.
+---
 
 ## When to use something else
 
-memorio is intentionally not everything.
+- **A strict Redux-style architecture** - when you need action pipelines, extensive middleware, event-sourcing, or mature time-travel tooling. Memorio can integrate rather than replace - see [`markdown/REDUX.md`](./markdown/REDUX.md).
+- **A server database** - for authoritative persistence, multi-user authorization, or server-side transactions.
+- **A dedicated secrets manager** - for high-privilege credentials, encryption key management, or regulated data at rest. Memorio's encryption is client-side and key-management is your responsibility - see [`SECURITY.md`](./SECURITY.md).
+- **A dedicated vector database** - for true embedding similarity search. Memorio manages structured memory (preferences, decisions, facts), not embeddings.
 
-- **Need strict Redux-style architecture** (action pipelines, reducer-based transitions, extensive middleware, time-travel debugging, event-sourcing)? memorio can integrate with such systems rather than replace them.
-- **Need a server database** (authoritative persistence, multi-user authorization, server-side transactions, backend-controlled access)? Use one — memorio doesn't provide it.
-- **Need true embedding similarity / vector search**? Pair a dedicated vector database with `memorio.memory`, which can still manage the lifecycle and metadata of the retrieved knowledge.
+---
 
 ## Design philosophy
 
-1. **Local first** — the application stays useful when the network disappears.
-2. **Persistence is optional** — start in memory, persist only when it provides value.
-3. **The cloud is optional** — remote sync extends the local application; it does not define it.
-4. **Use the right primitive** — don't put relational data in a key/value store, or semantic memory in ordinary state.
-5. **Memory has meaning** — confidence, source, type, scope, TTL, tags, history, status. That's different from simply storing a value.
-6. **Global access is a convenience, not a requirement** — both `import 'memorio'` and `import { state } from 'memorio'` are valid; memorio does not impose one architecture.
-7. **Tell the truth about boundaries** — local data is not automatically secure, persistence is not authorization, structured memory is not automatically AI semantic search.
-8. **Keep the common case tiny:**
-   ```ts
-   import 'memorio'
-   state.value = 42
-   ```
-   Everything else is there when you need it.
-
-## A mental model
-
-```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
+1. **Local first** - the app stays useful when the network disappears.
+2. **Persistence is optional** - start in memory, persist only when it adds value.
+3. **The cloud is optional** - sync extends the local app; it doesn't define it.
+4. **Use the right primitive** - relational data belongs in SQL, not a kv store; memory isn't the same as ordinary state.
+5. **Memory has meaning** - confidence, source, type, scope, TTL, tags, history, status: more than "just a value."
+6. **Memory belongs to whoever it's about** - structured and inspectable by default, encryptable with a key the vendor doesn't have to hold.
+7. **Global access is explicit** - opt in with `import 'memorio/global'`, or keep it explicit with named imports.
+8. **Tell the truth about boundaries** - encryption is opt-in (not default), contexts aren't authorization, and there's no embedding search unless paired with one.
+9. **Keep the common case tiny** - `state.value = 42` is a complete, valid program.
 
-### 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