memorio 4.9.35 → 5.1.0

package/llms.txt

@@ -2,7 +2,7 @@
 
 ## Overview
 
-**Memorio** is a cross-platform state management library that 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,13 +21,17 @@ 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
 
+Memorio does not expose APIs on `globalThis` by default. Use explicit named imports for normal application code:
+
 ```javascript
-import 'memorio'
+import { state, useObserver } from 'memorio'
 
 // Set reactive state
 state.user = { name: 'Sara', role: 'admin' }
@@ -40,6 +44,15 @@ useObserver(
 )
 ```
 
+```note
+To opt in to global access (state, store, session, cache, idb, sqlite, observer, useObserver on `globalThis`), use the explicit global entrypoint:
+
+```javascript
+import 'memorio/global'
+```
+
+This is independent of bundler environment detection (no `import.meta.env.DEV`, no `process.env.NODE_ENV` checks).
+
 ## API Reference
 
 ### `state` - Reactive State
@@ -238,7 +251,7 @@ observer.removeAll()
 Primary way to observe state changes in React components.
 
 ```jsx
-import 'memorio'
+import { useObserver, state } from 'memorio'
 import { useReducer } from 'react'
 
 function Counter() {
@@ -305,7 +318,7 @@ memorio.logger.exportLogs()   // JSON string of all history
 
 ## Platform Detection
 
-Access via `memorio.*` after `import 'memorio'`:
+Access via `memorio.*` after importing from `memorio`:
 
 ```javascript
 memorio.isBrowser()       // true in Chrome, Firefox, Safari
@@ -338,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.
@@ -429,6 +477,63 @@ memorio.canRedo() // true
 
 ### `memorio.trace()` - Mutation Log
 
+Every mutation is recorded as a structured `Mutation` with a unique ID, HLC timestamp, operation, before/after values, source attribution, and optional transaction ID:
+
+```javascript
+memorio.enableHistory(true)
+state.user.name = 'Sara'
+
+const log = memorio.trace()
+// [{
+//   id: 'm_01h...', path: 'user.name', operation: 'set',
+//   before: undefined, after: 'Sara',
+//   timestamp: 1780000000, hlc: 'hlc:1780000000:00:abc1',
+//   action: 'set', newValue: 'Sara', previousValue: undefined,
+//   source: undefined, transactionId: undefined
+// }]
+```
+
+### Mutation Engine (Memorio 5)
+
+`memorio.mutate()` records a mutation with source attribution:
+
+```javascript
+import { memorio } from 'memorio'
+
+memorio.enableHistory(true)
+
+const m = memorio.mutate('state.user.role', 'admin', {
+  source: 'permissions.enableAdmin'
+})
+console.log(m.id)        // "m_01h4f2k7..."
+console.log(m.operation) // "set"
+console.log(m.before)    // undefined
+console.log(m.after)     // "admin"
+console.log(m.source)    // "permissions.enableAdmin"
+```
+
+Transactions group related mutations atomically:
+
+```javascript
+const tx = memorio.transaction('user.migration', 'Migrate to v2')
+
+state.user.role = 'admin'
+state.user.v2 = true
+
+memorio.commitTransaction()  // or memorio.abortTransaction() to roll back
+
+// Named imports for fine-grained control:
+import { beginTransaction, commitTransaction, abortTransaction, currentTransaction } from 'memorio'
+```
+
+Patch utilities convert mutations to RFC 6902-style patches for replay, sync, and simulation:
+
+```javascript
+import { mutationToPatch, diffToPatch, canMerge, mergePatches } from 'memorio'
+```
+
+### `memorio.trace()` - Mutation Log
+
 ```javascript
 memorio.trace()
 // [{ path, action, newValue, previousValue, timestamp }, ...]
@@ -452,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

@@ -0,0 +1,134 @@
+> **Status:** Accepted
+> **Date:** 2026-09-12
+> **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 v5.1.0
+
+## 1. Security Audit
+
+### Findings
+
+| Severity | Issue | Status |
+|----------|-------|--------|
+| None | Secrets/credentials in source | ✅ Clean - all "token"/"secret" are in examples/test fixtures |
+| None | Dynamic code execution (`eval`, `new Function`) | ✅ Not present |
+| None | Prototype pollution (`__proto__`, `constructor.prototype`) | ✅ Not present |
+| None | XSS vectors (`innerHTML`, `document.write`) | ✅ Not present |
+| None | SQL injection (sqlite module) | ✅ Uses parameterized statements via sql.js `stmt.bind()` |
+| Low | `console.warn`/`console.error` used outside catch blocks | ⚠️ Present in `functions/state/index.ts` guard clauses (state locked/protected) |
+| None | Namespace isolation in memory system | ✅ Documented trust model with per-namespace storage keys |
+
+### Actions Taken
+- **Removed `__DEV__` references**: All bare `__DEV__` references removed from source code and documentation
+- **Updated comments**: Replaced `__DEV__` mentions in JSDoc comments with `DEV`/runtime detection references
+
+---
+
+## 2. Performance Audit
+
+### Findings
+
+| Issue | Impact | Status |
+|-------|--------|--------|
+| `wrapperCache` in `state/index.ts` uses `WeakMap` | ✅ No memory leak - GC cleans up orphaned wrappers |
+| `JSON.parse(JSON.stringify())` in 3 locations | Low - only for snapshot/list/inspect operations, not hot loops | ✅ Acceptable |
+| `setTimeout` in sqlite persistence | ✅ Async, doesn't block main thread |
+| No `console.log` in hot paths | ✅ All logging uses `console.debug` |
+
+### Actions Taken
+- **No performance changes needed**: Architecture is already optimized for the use case
+
+---
+
+## 3. Reliability Audit
+
+### Findings
+
+| Issue | Location | Risk | Status |
+|-------|----------|------|--------|
+| DevTools using `globalThis.state/store/session/cache` | `functions/devtools/index.ts` | High - fails when globals not initialized (prod mode) | ✅ Fixed |
+| `console.error` in non-catch contexts | `functions/state/index.ts:182,188,194,200` | Low - noisy console in strict mode | ⚠️ Deferred (UX choice) |
+
+### Actions Taken
+
+**DevTools module deduplication (critical fix)**:
+- Removed direct `globalThis.state/store/session/cache` access from `functions/devtools/index.ts`
+- Replaced with singleton access via private `globalThis` keys (`__memorio_state_instance__`, `__memorio_store_instance__`, `__memorio_session_instance__`, `__memorio_cache_instance__`)
+- These keys are the same ones used by the modules themselves for singleton deduplication
+- This also fixes a **circular import issue** that arose from naive direct imports (state → dispatch → ... → devtools cycle)
+- Access via private singleton keys is safe because they are set at module initialization, before `core/global.ts` runs
+- Updated 3 functions: `inspect()`, `stats()`, `exportData()`/`importData()`/`clear()`/`watch()`/`help()`
+- Removed emoji prefixes from console output for cleaner logs
+- Changed `console.error` to `console.debug` for consistency
+
+---
+
+## 4. Code Quality Audit
+
+### Findings
+
+| Issue | Status |
+|-------|--------|
+| Duplicate storage pattern in `store` and `session` | ✅ Pre-existing - same `_getPrefix/_prefixKey/_read/_write/_remove` pattern (acceptable) |
+| `console.warn` vs `console.debug` inconsistency in `state/index.ts` | ⚠️ Present - state lock/protected uses `console.error` |
+| JSDoc coverage on public functions | ✅ Complete |
+
+---
+
+## 5. Documentation Audit
+
+### Actions Taken
+- **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 v5.1.0 entry documenting all fixes
+
+---
+
+## 6. Lint & Build Verification
+
+```
+✅ oxlint: 0 warnings, 0 errors (60 files, 92 rules, 8 threads)
+✅ Production build: 0 __DEV__ references in dist/index.js and dist/index.cjs
+✅ Tests: 200 passed, 4 skipped, 1 todo (0 failures)
+✅ Files deployed to A:/Gitea/picla.app.examplepage/node_modules/memorio/
+```
+
+---
+
+## 7. Additional Code Quality Fixes
+
+| File | Issue | Fix |
+|------|-------|-----|
+| `functions/memory/journal.ts:62` | Unused `serialize` function | Removed |
+| `core/hlc.ts:83` | Unused `incoming` parameter | Renamed to `_incoming` |
+| `functions/memory/index.ts:553,556` | Unnecessary regex escapes `\.` | Changed to `.` |
+| `functions/devtools/index.ts` | Used `globalThis.state` instead of imports | Replaced with singleton keys |
+| `.oxlintrc.json` | Missing lint config | Created with ignore patterns + rule overrides |
+| All files | `__DEV__` references in comments | Removed/replaced |
+
+---
+
+## Summary of Files Modified
+
+| File | Change |
+|------|--------|
+| `core/env.ts` | Removed `__DEV__` from comments |
+| `core/global.ts` | Updated comments: `__DEV__` → runtime detection |
+| `functions/devtools/index.ts` | Fixed circular imports + globalThis access; removed `__DEV__`; use singleton keys |
+| `functions/memory/journal.ts` | Removed unused `serialize` function |
+| `core/hlc.ts` | Fixed unused parameter `_incoming` |
+| `functions/memory/index.ts` | Fixed regex escapes |
+| `functions/devtools/index.ts` | Fixed circular imports + globalThis access; use singleton keys |
+| `tests/vitest/vitest.config.ts` | Removed `__DEV__` from comments |
+| `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 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

@@ -0,0 +1,191 @@
+> **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

package/markdown/DEVTOOLS.md

@@ -0,0 +1,128 @@
+> **Status:** Published
+> **Date:** 2026-09-12
+> **Scope**: API Reference
+> **Standard**: Memorio API Specification v5
+>
+---
+# Memorio DevTools
+
+> 🖥️ **Browser Only**: This feature is only available in browser console
+
+Browser console debugging tools for inspecting and managing Memorio state.
+
+## Quick Start
+
+```javascript
+// Load memorio first, then enable global API
+import 'memorio/global'
+```
+
+## Available Methods
+
+### inspect()
+
+Inspect all Memorio modules in the console.
+
+```javascript
+memorio.devtools.inspect()
+```
+
+### stats()
+
+Get statistics about all modules.
+
+```javascript
+memorio.devtools.stats()
+// Returns: { stateKeys, storeKeys, sessionKeys, cacheKeys, idbDatabases, lastUpdate }
+```
+
+### clear(module)
+
+Clear data from a specific module.
+
+```javascript
+memorio.devtools.clear('state')
+memorio.devtools.clear('store')
+memorio.devtools.clear('session')
+memorio.devtools.clear('cache')
+```
+
+### clearAll()
+
+Clear all Memorio data.
+
+```javascript
+memorio.devtools.clearAll()
+```
+
+### watch(module, path)
+
+Watch a specific path for changes.
+
+```javascript
+memorio.devtools.watch('state', 'user.name')
+```
+
+### exportData()
+
+Export all data as JSON.
+
+```javascript
+const json = memorio.devtools.exportData()
+console.debug(json)
+```
+
+### importData(jsonString)
+
+Import data from JSON.
+
+```javascript
+memorio.devtools.importData('{"state":{"key":"value"}}')
+```
+
+### help()
+
+Show help information.
+
+```javascript
+memorio.devtools.help()
+```
+
+## Console Shortcuts
+
+Memorio provides global shortcuts for quick access:
+
+```javascript
+$state    // globalThis.state
+$store    // globalThis.store
+$session  // globalThis.session
+$cache    // globalThis.cache
+```
+
+## Examples
+
+### Inspect current state
+
+```javascript
+memorio.devtools.inspect()
+```
+
+### Export and restore state
+
+```javascript
+// Export
+const backup = memorio.devtools.exportData()
+
+// Later... import
+memorio.devtools.importData(backup)
+```
+
+### Monitor changes
+
+```javascript
+// Watch a specific path
+memorio.devtools.watch('state', 'counter')
+
+// Now changes will be logged to console
+state.counter = 42 // Console shows: 👁 Change: state.counter = 42
+```