memorio 5.0.0 → 5.1.1

package/llms.txt

@@ -2,7 +2,7 @@
 
 ## Overview
 
-**Memorio** is an application state intelligence runtime. It manages application state, remembers how it changed, understands causal relationships, enables deterministic replay, and can simulate the impact of future changes. It provides reactive state, persistence, and observation capabilities with zero dependencies. It works in Node.js, Deno, browsers, and edge environments.
+**Memorio** is the memory layer for AI agents and apps - owned by the user, not the vendor. It manages application state, remembers how it changed, understands causal relationships, enables deterministic replay, and can simulate the impact of future changes. It provides reactive state, persistence, observation, and optional AES-GCM encryption capabilities with zero production dependencies. It works in Node.js, Deno, browsers, and edge environments.
 
 ```
 npm i memorio
@@ -21,8 +21,10 @@ Memorio provides 6 storage modules plus utilities:
 | `session` | sessionStorage | Dies with browser tab; falls back to non-durable in-memory `Map` in Node.js/Deno |
 | `cache` | In-memory cache | Fastest read, no persistence |
 | `idb` | IndexedDB | Structured, async, persistent (browser-only - disabled in Node.js/Deno) |
+| `sqlite` | SQLite via sql.js (WebAssembly) | Browser-only relational SQL |
 | `observer` | Object watcher | Legacy; string-based paths, not statically checked against `state`'s shape |
 | `useObserver` | React hook | Auto-discovery of state paths |
+| `encryption` | AES-GCM + PBKDF2 | Encrypt/decrypt values, store/session integration |
 
 ## Quick Start
 
@@ -349,23 +351,58 @@ By default, `state` is a **shared global namespace** - a value set in one place
 To isolate a slice of state (e.g. per tenant, per request), create an explicit context:
 
 ```javascript
+// Basic context: namespace isolation via key prefixes
 const ctx = memorio.createContext('tenant-name')
 ctx.state.user = { name: 'Isolated' }
 
 console.debug(state.user) // undefined - separate namespace from ctx.state
 
-memorio.listContexts()
-memorio.deleteContext('context-id')
-memorio.isolate('tenant-name')  // alias for createContext
+// Encrypted context: namespace + cryptographic isolation
+const key = await memorio.encryption.deriveKey('tenant-password', 'tenant-salt')
+const ctx = memorio.createContext('tenant-name', { encryptionKey: key })
+await ctx.store.set('secrets', { apiKey: 'sk-12345' })  // encrypted at rest
+const secrets = await ctx.store.get('secrets')           // decrypted on read
 ```
 
 Isolation is implemented as a **key-prefix convention** inside the same underlying storage, not a hard memory or process boundary. In a shared Node.js process or an edge isolate that may be reused across requests:
 
 - generate context IDs from trusted server-side data, never directly from client-controlled input, to prevent collisions or spoofing;
 - don't treat this as your only isolation layer for data that must not cross tenants - enforce that at the process/request level as well.
+- when encryption is enabled on a context, encrypted values provide a cryptographic wall on top of the namespace prefix, but key management is your responsibility.
 
 `getCapabilities().sessionId` provides a per-session identifier for browser contexts but is not itself an isolation mechanism - use `createContext` for that.
 
+### `memorio.encryption` - Encryption (opt-in)
+
+Built on the Web Crypto API (`crypto.subtle`). AES-GCM for authenticated encryption, PBKDF2 for password-based key derivation. Works in browsers, Node.js 18+, Deno 1.13+, and modern edge runtimes.
+
+```javascript
+// Derive a key from a password (PBKDF2, 600k iterations - NIST SP 800-132)
+const key = await memorio.encryption.deriveKey('password', 'salt')
+
+// Or generate a random key
+const key = await memorio.encryption.generateKey()
+
+// Encrypt/decrypt
+const envelope = await memorio.encryption.encrypt({ secret: 'value' }, key)
+const original = await memorio.encryption.decrypt(envelope, key)
+
+// Password-based convenience (returns JSON string, for direct persistence)
+const json = await memorio.encryption.encryptWithPassword(value, 'password', 'salt')
+const decrypted = await memorio.encryption.decryptWithPassword(json, 'password', 'salt')
+
+// Store-level encryption
+await store.set('api_token', secret, { encrypt: key })
+await store.get('api_token', { decrypt: key })
+
+// Or configure a default key for transparent encryption
+store.config({ encryptionKey: key })
+await store.set('api_token', secret)  // encrypted automatically
+const token = store.get('api_token')  // decrypted automatically (returns a Promise)
+```
+
+> Encryption is **opt-in** - no layer encrypts by default. Key management is the application's responsibility. Never hardcode keys in client bundles.
+
 ### `memorio.typed<T>()` - Typed Store (compile-time safety)
 
 Returns the global `state` proxy cast to type `T`. The same Proxy instance - no overhead. Use for TypeScript autocomplete and static type checking.
@@ -520,7 +557,7 @@ memorio.stateSchema()    // [{ path, type, defined }, ...] - full tree report
 - No `eval`, no dynamic code execution, no obfuscation, no hardcoded secrets.
 - Inputs validated, keys sanitized before use.
 - Secure random session IDs via `crypto.randomUUID`.
-- Data in `store`, `session`, and `idb` is **not encrypted** - these are thin wrappers over browser storage APIs that persist data in the clear on the user's device. Add your own encryption layer before storing tokens, secrets, or regulated personal data there.
+- Data in `store`, `session`, and `idb` is **not encrypted by default** - these are thin wrappers over browser storage APIs that persist data in the clear on the user's device. For sensitive data (tokens, secrets, PII), use `memorio.encryption` (AES-GCM + PBKDF2) to encrypt before persisting, or enable auto-encrypt via `store.config({ encryptionKey })` / `createContext(id, { encryptionKey })`. Key management is the application's responsibility.
 
 Engineering practices are informed by recognized guidance (e.g. NIST SP 800-53 practices) as a design input - this is a statement about how the library is built, not a compliance certification, and no third-party audit has been performed. Report security issues privately (see `SECURITY.md`) rather than in a public issue.
 

package/markdown/AUDIT-REPORT.md

@@ -1,11 +1,10 @@
 > **Status:** Accepted
 > **Date:** 2026-09-12
-> **Deciders:** Memorio 5.x Core Team
-> **Scope**: Security (NIST/OWASP/NSA), Performance, Reliability, Code Quality
-> **Standard**: NIST SP 800-53, OWASP ASVS, NSA Cybersecurity Guidelines
+> **Scope**: Internal self-audit - Security, Performance, Reliability, Code Quality
+> **Note**: This is a self-conducted audit, not a certified third-party assessment. No claim of conformance to any external standard (NIST, OWASP, NSA, etc.) is made or implied.
 >
 ---
-# Audit Report - Memorio v4.9.5
+# Audit Report - Memorio v5.1.0
 
 ## 1. Security Audit
 
@@ -81,12 +80,12 @@
 ## 5. Documentation Audit
 
 ### Actions Taken
-- **Merged changelogs**: Combined `.project/CHANGELOG.md` (v4.9.5 detailed) into `.project/markdown/CHANGELOG.md`
-- **Updated version references**: Changed v3.0.2 → v4.9.5 throughout
+- **Merged changelogs**: Combined `.project/CHANGELOG.md` (v5.1.0 detailed) into `.project/markdown/CHANGELOG.md`
+- **Updated version references**: Changed v3.0.2 → v5.1.0 throughout
 - **Updated stack**: Jest → vitest, `config/` → `core/`
 - **Removed `__DEV__` mentions**: All documentation comments updated
 - **Added "Module deduplication strategy"** section to `docs/README.md`
-- **Updated CHANGELOG** with v4.9.5 entry documenting all fixes
+- **Updated CHANGELOG** with v5.1.0 entry documenting all fixes
 
 ---
 
@@ -129,7 +128,7 @@
 | `types/env.d.ts` | Removed `__DEV__` from comments |
 | `.oxlintrc.json` | New lint configuration |
 | `tsup.config.ts` | Disabled minification + enabled sourcemaps to avoid socket.dev false positives |
-| `.project/markdown/CHANGELOG.md` | Merged changelogs, added v4.9.5 entry |
+| `.project/markdown/CHANGELOG.md` | Merged changelogs, added v5.1.0 entry |
 | `.project/markdown/PROJECT.md` | Updated version, stack, structure (was memorio.md) |
 | `docs/README.md` | Added module deduplication strategy section |
 | `tests/scripts/update-node-modules-memorio.cjs` | New deploy script for user app |

package/markdown/CACHE.md

@@ -1,100 +1,191 @@
-> **Status:** Published
-> **Date:** 2026-09-12
-> **Deciders:** Memorio 5.x Core Team
-> **Scope**: API Reference
-> **Standard**: Memorio API Specification v5
->
----
+> **Status:** Published
+> **Date:** 2026-09-12
+> **Scope**: API Reference
+> **Standard**: Memorio API Specification v5
+>
+---
+
 # Cache - Memorio
-
-> ✅ **Universal**: Works in Browser, Node.js, Deno, and Edge Workers
-
-Cache provides in-memory storage with a simple API. Data is lost on page refresh or process restart.
-
-## Installation
-
-```bash
-npm install memorio
-```
-
-```javascript
-import { cache } from 'memorio';
-```
-
-> **Classic `import`**: `cache` is also available via the global entrypoint.
-> `import 'memorio/global'` exposes the same instance as `globalThis.cache`.
-
----
-
-## Quick Examples
-
-### Example 1: Basic Usage
-
-```javascript
-// Save data
-cache.set('username', 'Mario');
-cache.set('score', 1500);
-
-// Read data
-console.debug(cache.get('username')); // "Mario"
-console.debug(cache.get('score'));    // 1500
-```
-
-### Example 2: Intermediate
-
-```javascript
-// Store objects
-cache.set('user', { name: 'Luigi', level: 5 });
-const user = cache.get('user');
-console.debug(user.name); // "Luigi"
-
-// Remove single item
-cache.remove('username');
-
-// Clear all cache
-cache.removeAll();
-```
-
----
-
-## API Reference
-
-### Methods
-
-| Method | Parameters | Returns | Description |
-|--------|------------|---------|-------------|
-| `cache.get(name)` | `name: string` | `any` | Get value from cache |
-| `cache.set(name, value)` | `name: string, value: any` | `void` | Save value to cache |
-| `cache.remove(name)` | `name: string` | `boolean` | Remove single item |
-| `cache.removeAll()` | `none` | `boolean` | Clear all cache |
-
----
-
-## Storage Comparison
-
-| Feature | Cache | Store | Session | IDB |
-|---------|-------|-------|---------|-----|
-| Platform Support | All (universal) | Browser/Edge | Browser/Edge | Browser only |
-| Lifetime | Until refresh | Forever | Until tab closes | Forever |
-| Capacity | Unlimited | ~5-10 MB | ~5-10 MB | 50+ MB |
-| Use case | Temporary data | User preferences | Auth tokens | Large data |
-
----
-
-## Platform Support
-
-| Platform | Support | Notes |
-|----------|---------|-------|
-| Browser | ✅ Full | In-memory, lost on refresh |
-| Node.js | ✅ Full | In-memory, lost on restart |
-| Deno | ✅ Full | In-memory, lost on restart |
-| Edge Workers | ✅ Full | In-memory, lost on function cold start |
-
----
-
-## Best Practices
-
-1. Use for temporary data that doesn't need persistence
-2. Great for computed values or API response caching
-3. Data is lost on page refresh - don't use for important data
-4. Clear with `cache.removeAll()` when no longer needed
+
+
+> ✅ **Universal**: Works in Browser, Node.js, Deno, and Edge Workers
+
+
+
+Cache provides in-memory storage with a simple API. Data is lost on page refresh or process restart.
+
+
+
+## Installation
+
+
+
+```bash
+
+npm install memorio
+
+```
+
+
+
+```javascript
+
+import { cache } from 'memorio';
+
+```
+
+
+
+> **Classic `import`**: `cache` is also available via the global entrypoint.
+
+> `import 'memorio/global'` exposes the same instance as `globalThis.cache`.
+
+
+
+---
+
+
+
+## Quick Examples
+
+
+
+### Example 1: Basic Usage
+
+
+
+```javascript
+
+// Save data
+
+cache.set('username', 'Mario');
+
+cache.set('score', 1500);
+
+
+
+// Read data
+
+console.debug(cache.get('username')); // "Mario"
+
+console.debug(cache.get('score'));    // 1500
+
+```
+
+
+
+### Example 2: Intermediate
+
+
+
+```javascript
+
+// Store objects
+
+cache.set('user', { name: 'Luigi', level: 5 });
+
+const user = cache.get('user');
+
+console.debug(user.name); // "Luigi"
+
+
+
+// Remove single item
+
+cache.remove('username');
+
+
+
+// Clear all cache
+
+cache.removeAll();
+
+```
+
+
+
+---
+
+
+
+## API Reference
+
+
+
+### Methods
+
+
+
+| Method | Parameters | Returns | Description |
+
+|--------|------------|---------|-------------|
+
+| `cache.get(name)` | `name: string` | `any` | Get value from cache |
+
+| `cache.set(name, value)` | `name: string, value: any` | `void` | Save value to cache |
+
+| `cache.remove(name)` | `name: string` | `boolean` | Remove single item |
+
+| `cache.removeAll()` | `none` | `boolean` | Clear all cache |
+
+
+
+---
+
+
+
+## Storage Comparison
+
+
+
+| Feature | Cache | Store | Session | IDB |
+
+|---------|-------|-------|---------|-----|
+
+| Platform Support | All (universal) | Browser/Edge | Browser/Edge | Browser only |
+
+| Lifetime | Until refresh | Forever | Until tab closes | Forever |
+
+| Capacity | Unlimited | ~5-10 MB | ~5-10 MB | 50+ MB |
+
+| Use case | Temporary data | User preferences | Auth tokens | Large data |
+
+
+
+---
+
+
+
+## Platform Support
+
+
+
+| Platform | Support | Notes |
+
+|----------|---------|-------|
+
+| Browser | ✅ Full | In-memory, lost on refresh |
+
+| Node.js | ✅ Full | In-memory, lost on restart |
+
+| Deno | ✅ Full | In-memory, lost on restart |
+
+| Edge Workers | ✅ Full | In-memory, lost on function cold start |
+
+
+
+---
+
+
+
+## Best Practices
+
+
+
+1. Use for temporary data that doesn't need persistence
+
+2. Great for computed values or API response caching
+
+3. Data is lost on page refresh - don't use for important data
+
+4. Clear with `cache.removeAll()` when no longer needed

package/markdown/DEVTOOLS.md

@@ -1,6 +1,5 @@
 > **Status:** Published
 > **Date:** 2026-09-12
-> **Deciders:** Memorio 5.x Core Team
 > **Scope**: API Reference
 > **Standard**: Memorio API Specification v5
 >

package/markdown/DISPATCH.md

@@ -1,6 +1,5 @@
 > **Status:** Published
 > **Date:** 2026-09-12
-> **Deciders:** Memorio 5.x Core Team
 > **Scope**: API Reference
 > **Standard**: Memorio API Specification v5
 >

package/markdown/HISTORY.md

@@ -1,6 +1,5 @@
 > **Status:** Published
 > **Date:** 2026-09-12
-> **Deciders:** Memorio 5.x Core Team
 > **Scope**: API Reference
 > **Standard**: Memorio API Specification v5
 >

package/markdown/IDB.md

@@ -1,6 +1,5 @@
 > **Status:** Published
 > **Date:** 2026-09-12
-> **Deciders:** Memorio 5.x Core Team
 > **Scope**: API Reference
 > **Standard**: Memorio API Specification v5
 >

package/markdown/IMPORT.md

@@ -1,6 +1,5 @@
 > **Status:** Published
 > **Date:** 2026-09-12
-> **Deciders:** Memorio 5.x Core Team
 > **Scope**: API Reference
 > **Standard**: Memorio API Specification v5
 >

package/markdown/INSPECT.md

@@ -1,6 +1,5 @@
 > **Status:** Published
 > **Date:** 2026-09-12
-> **Deciders:** Memorio 5.x Core Team
 > **Scope**: API Reference
 > **Standard**: Memorio API Specification v5
 >

package/markdown/LOGGER.md

@@ -1,6 +1,5 @@
 > **Status:** Published
 > **Date:** 2026-09-12
-> **Deciders:** Memorio 5.x Core Team
 > **Scope**: API Reference
 > **Standard**: Memorio API Specification v5
 >

package/markdown/MEMORY-ATTACHMENT.md

@@ -1,6 +1,5 @@
 > **Status:** Published
 > **Date:** 2026-09-12
-> **Deciders:** Memorio 5.x Core Team
 > **Scope**: API Reference
 > **Standard**: Memorio API Specification v5
 >

package/markdown/MEMORY.md

@@ -1,6 +1,5 @@
 > **Status:** Published
 > **Date:** 2026-09-12
-> **Deciders:** Memorio 5.x Core Team
 > **Scope**: API Reference
 > **Standard**: Memorio API Specification v5
 >

package/markdown/OBSERVER.md

@@ -1,6 +1,5 @@
 > **Status:** Published
 > **Date:** 2026-09-12
-> **Deciders:** Memorio 5.x Core Team
 > **Scope**: API Reference
 > **Standard**: Memorio API Specification v5
 >