memorio 4.7.1 → 4.7.3

package/README.md

@@ -13,7 +13,7 @@
 ![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.
+### One import. Global state, persistence, and a IndexedDB layer - done.
 
 ```javascript
 import 'memorio'
@@ -21,7 +21,7 @@ import 'memorio'
 state.user = { name: 'Sara' }   // reactive, everywhere, instantly
 ```
 
-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 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.
 
 ---
 
@@ -31,26 +31,28 @@ No provider tree. No reducers. No actions to dispatch before you can change a nu
 2. [Installation](#installation)
 3. [Quick Start](#quick-start)
 4. [API Reference](#api-reference)
-5. [Cross-Platform Behavior](#cross-platform-behavior)
-6. [Context Isolation (multi-tenant)](#context-isolation-multi-tenant)
-7. [Security](#security)
-8. [License](#license)
+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)
 
 ---
 
 ## 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.
+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 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.
-- 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.
-- Your isolation requirements are a security boundary, not a convenience — see [Context Isolation](#context-isolation-multi-tenant) before you rely on it for that.
+- 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."
 
@@ -63,7 +65,7 @@ npm i memorio
 # pnpm add memorio
 # yarn add memorio
 
-# Optional — only if you use the React hook
+# Optional - only if you use the React hook
 npm i react react-dom
 ```
 
@@ -71,7 +73,7 @@ npm i react react-dom
 
 ## Quick Start
 
-### Global style — the whole point of memorio
+### Global style - the whole point of memorio
 
 ```typescript
 import 'memorio' // once, at your entry point
@@ -85,7 +87,7 @@ useObserver(
 )
 ```
 
-### Named imports — same instances, explicit about it
+### Named imports - same instances, explicit about it
 
 ```typescript
 import { state, store, session, cache, idb, observer, useObserver, dispatch, memorio } from 'memorio'
@@ -102,13 +104,13 @@ function Counter() {
 }
 ```
 
-Two styles, one engine underneath — use whichever reads better in your codebase.
+Two styles, one engine underneath - use whichever reads better in your codebase.
 
 ---
 
 ## API Reference
 
-### `state` — reactive, volatile, Proxy-based
+### `state` - reactive, volatile, Proxy-based
 
 ```javascript
 state.user = { name: 'Sara', role: 'admin' }
@@ -125,7 +127,7 @@ state.config.maxUsers = 200   // throws: state 'config' is locked
 state.config.unlock()
 ```
 
-### `store` — the value that survives a refresh
+### `store` - the value that survives a refresh
 
 ```javascript
 store.set('preferences', { theme: 'dark' })
@@ -133,21 +135,21 @@ store.get('preferences')      // { theme: 'dark' } or null
 store.isPersistent            // true when backed by real localStorage
 ```
 
-### `session` — lives as long as the tab does
+### `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
+### `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
+### `idb` - typed, async, structured tables without the ceremony
 
 ```javascript
 await idb.db.create('my-db')
@@ -156,9 +158,9 @@ 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.
+> IndexedDB is a browser-only primitive - see [Cross-Platform Behavior](#cross-platform-behavior) for what happens off the browser.
 
-### `observer` / `useObserver` — watch a path, react to it
+### `observer` / `useObserver` - watch a path, react to it
 
 ```javascript
 observer('state.user', (newVal, oldVal) => {
@@ -168,14 +170,14 @@ observer('state.user', (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.
 
-### `dispatch` — the event bus underneath it all
+### `dispatch` - the event bus underneath it all
 
 ```javascript
 memorio.dispatch.listen('state.user', (event) => console.debug(event.detail))
 memorio.dispatch.set('state.user', { detail: { name: 'Sara' } })
 ```
 
-### `devtools` — see everything, instantly
+### `devtools` - see everything, instantly
 
 ```javascript
 memorio.devtools.inspect()
@@ -185,32 +187,237 @@ memorio.devtools.exportData()
 
 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.
 
-### `logger` — a black box for every change
+### `logger` - a black box for every change
 
 ```javascript
 memorio.logger.configure({ enabled: true, logToConsole: true })
 memorio.logger.getHistory()
 ```
 
-> 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).
+> 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
+```
+
+The same data is accessible via the global `state` proxy — `app` and `state` are identical instances:
+
+```typescript
+state.user = { name: 'Sara', age: 30, email: 'sara@test.com' }
+app.user.name   // 'Sara' — same Proxy
+```
+
+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.
+
+```typescript
+import 'memorio'
+
+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
+```
+
+Custom validator functions are also supported:
+
+```typescript
+memorio.registerSchema('theme', (val) => {
+  return val === 'light' || val === 'dark'
+    ? true
+    : 'theme must be "light" or "dark"'
+})
+
+state.theme = 'purple'  // rejected: "theme must be light or dark"
+state.theme = 'dark'    // accepted
+```
+
+Manual validation without writing:
+
+```typescript
+memorio.validate('user', { name: 'Sara', email: 'sara@test.com' })
+// { valid: true }
+
+memorio.validate('user', { name: 'Sara' })
+// { valid: false, errors: ["user: missing required property 'email'"] }
+```
+
+Manage registered schemas:
+
+```typescript
+memorio.listSchemas()           // ['user', 'theme']
+memorio.unregisterSchema('theme')  // removes the validator
+```
+
+**Typed + Schema** — combine both for full safety:
+
+```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
+```
+
+See [Schema Validation docs](markdown/SCHEMA.md) for the full schema definition reference.
+
+---
+
+## Memory System
+
+`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.
+
+### Core API
+
+```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'
+})
+
+// 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
+
+```ts
+// context() — returns ranked, relevant memories
+const context = await memorio.memory.context({
+  tags: 'user',
+  types: ['preference', 'decision'],
+  minConfidence: 0.7,
+  maxEntries: 10
+})
+// → [{ key, value, relevance, age, confidence, ... }]
+```
+
+### Memory Entry Model
+
+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:
+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:
 
 | 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` |
+| `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.
+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()
@@ -234,10 +441,10 @@ const ctx = memorio.createContext('tenant-123')
 ctx.state.user = { name: 'Isolated' }
 ctx.store.set('settings', { theme: 'dark' })
 
-console.debug(state.user) // undefined — separate namespace
+console.debug(state.user) // undefined - separate namespace
 ```
 
-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.
+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.
 
 ---
 
@@ -248,9 +455,9 @@ Handy for keeping per-tenant or per-request state from colliding in the same pro
 - Session IDs generated via `crypto.randomUUID`.
 - Inputs validated, keys sanitized, errors caught at module boundaries.
 
-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.
+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.
 
-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.
+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.
 
 ---
 

package/SECURITY.md

@@ -24,15 +24,15 @@ Memorio follows NIST and NSA security standards at the enterprise level.
 ## OWASP Compliance
 
 Addresses OWASP Top 10 (2021):
-- A01:2021 — Broken Access Control (global object protection, property locks)
-- A02:2021 — Cryptographic Failures (crypto.randomUUID for session IDs)
-- A03:2021 — Injection (CSS sanitization in devtools)
-- A05:2021 — Security Misconfiguration (minimal surface area, no bundled secrets)
-- A06:2021 — Vulnerable and Outdated Components (regular npm audit, Socket.dev)
-- A07:2021 — Identification and Authentication Failures (N/A — library, no auth)
-- A08:2021 — Software and Data Integrity Failures (strict tsconfig, lock files)
-- A09:2021 — Security Logging and Monitoring Failures (DevTools inspect, Logger module)
-- A10:2021 — Server-Side Request Forgery (N/A — no network requests)
+- A01:2021 - Broken Access Control (global object protection, property locks)
+- A02:2021 - Cryptographic Failures (crypto.randomUUID for session IDs)
+- A03:2021 - Injection (CSS sanitization in devtools)
+- A05:2021 - Security Misconfiguration (minimal surface area, no bundled secrets)
+- A06:2021 - Vulnerable and Outdated Components (regular npm audit, Socket.dev)
+- A07:2021 - Identification and Authentication Failures (N/A - library, no auth)
+- A08:2021 - Software and Data Integrity Failures (strict tsconfig, lock files)
+- A09:2021 - Security Logging and Monitoring Failures (DevTools inspect, Logger module)
+- A10:2021 - Server-Side Request Forgery (N/A - no network requests)
 
 ## Reporting Security Issues
 
@@ -44,5 +44,5 @@ If you find a security vulnerability:
 Do not open public issues for security vulnerabilities.
 
 ---
-*Document version: 2.0 — Last updated: 2026-05-19*
+*Document version: 2.0 - Last updated: 2026-05-19*
 *Owner: BigLogic Security Team*

package/SUMMARY.md

@@ -13,6 +13,20 @@
 * [Session](markdown/SESSION.md) - Temporary sessionStorage management
 * [IDB](markdown/IDB.md) - IndexedDB for large data storage
 
+## Typed & Validated
+
+* [Typed Stores](markdown/TYPED.md) - Compile-time type safety for state access
+* [Schema Validation](markdown/SCHEMA.md) - Runtime validation of state mutations
+
+## History & Introspection
+
+* [History](markdown/HISTORY.md) - Snapshot, diff, undo/redo, trace
+* [Introspection](markdown/INSPECT.md) - stateKeys, pathExists, stateType, stateSchema
+
+## Memory System
+
+* [Memory](markdown/MEMORY.md) - Semantic memory layer with TTL, confidence, scopes
+
 ## Platform & Compatibility
 
 * [Platform & Context Isolation](markdown/PLATFORM.md) - Cross-platform support, session isolation