memorio 4.9.7 → 4.9.8

package/AGENTS.md

@@ -0,0 +1,126 @@
+# AGENTS.md — working with `memorio`
+
+Operational conventions for AI coding agents working in a repository that depends on `memorio`.
+See `README.md` and `llms.txt` for the full API. This file is decision rules: what to reach for,
+when, and the specific footguns this library's own docs flag.
+
+## Read this before generating any `memorio` code
+
+`memorio`'s own `llms.txt` contains an explicit unresolved discrepancy:
+
+> **Locking — VERIFY BEFORE PUBLISHING:** one source describes per-key locking
+> (`state.config.lock()` freezes only `config`); another describes global locking
+> (`state.lock()` / `state.unlock()` freezing everything). Do not generate code against this
+> section until it's resolved against the real source.
+
+**Do not write or suggest `.lock()` / `.unlock()` calls with a confident claim about scope**
+(per-key vs. global) until you've confirmed the actual signature against the installed
+package's type definitions or source — `node_modules/memorio/dist/*.d.ts` — in the target repo.
+If you can't confirm it, say so explicitly rather than picking one behavior and presenting it
+as fact.
+
+## Choosing a layer
+
+Don't default to `state` for everything just because it's the one-liner in the README. Walk the
+decision tree from the README's ["Which layer should I use"](./README.md#which-layer-should-i-use)
+section, and in particular:
+
+| If the data is... | Use | Not |
+| --- | --- | --- |
+| UI-reactive, doesn't need to survive reload | `state` | `store` (unnecessary persistence) |
+| Small, must survive reload, any tab | `store` | `idb` (overkill for simple k/v) |
+| Must survive reload, this tab only | `session` | `store` (wrong scope) |
+| Relational, needs joins/SQL | `sqlite` | `idb` (no query language) |
+| Structured, needs confidence/TTL/source/history | `memory` | `state`/`store` (no lifecycle semantics) |
+| Large or structured, browser-only | `idb` | `store` (size/shape limits) |
+
+`sqlite` and `memory` answer different questions — "what data do I have" vs. "what does the app
+believe, and how sure is it." Don't reach for `memory` just because a value happens to come from
+an LLM; if it doesn't need confidence scoring, TTL, or supersession history, plain `state`/`store`
+is simpler and correct.
+
+## Server-side and multi-request code — read this first
+
+**`state` is a shared global namespace by default.** A value set in one request handler is
+visible to every other read of `state` in the same process. There is no automatic per-request
+or per-tab isolation.
+
+Before generating any server-side code (API route, edge function, worker) that could handle more
+than one user or request in the same process:
+
+1. Create an explicit context per request/tenant: `const ctx = memorio.createContext(id)`, then
+   read/write via `ctx.state`, never the bare global `state`.
+2. **Generate the context ID from trusted server-side data** (authenticated user id, request-scoped
+   token) — never directly from client-controlled input. Contexts are a key-prefix convention, not
+   a hard boundary, so a spoofable ID is a real collision risk, not just a naming concern.
+3. Treat context isolation as *organizational*, not a security boundary. It does not replace
+   authorization checks at the backend layer — never use it as the only thing standing between
+   one tenant's data and another's.
+
+If the code you're generating is client-side (a single browser tab, one user), bare `state` is
+fine — this concern is specific to shared-process server/edge code.
+
+## Known rough edges — don't paper over these in generated code
+
+- **`store.quota()` returns `[0, 0]` for the `localStorage` backend** — it's a placeholder, not a
+  real reading. Don't generate capacity-check logic that branches on its result for `store`.
+  It may be meaningful for `idb`, but confirm before relying on it there too.
+- **`idb` is disabled outright in Node.js/Deno** (calls warn and no-op). Any code that might run
+  outside a guaranteed browser context must guard: `if (idb.db.support())` or check
+  `memorio.getCapabilities().hasIndexedDB` — don't rely on the no-op warning alone reaching a log
+  anyone will see.
+- **`sqlite` persistence serializes the entire database on every flush** — not incremental. Never
+  generate code that calls a persisting write inside a loop; batch writes in one transaction/run
+  and persist once after the batch, per the README's guidance.
+- **`observer('state.some.path', cb)` paths are plain strings, unchecked against `state`'s actual
+  shape.** A typo or a later rename fails *silently* — the observer just never fires again. Prefer
+  `memorio.typed<T>()` + `registerSchema()` for anything you'd hate to have silently stop working,
+  and consider `memorio.pathExists('state.some.path')` as a startup sanity check for
+  observer-heavy code.
+- **`memory.context()` is rule-based (tags/type/confidence/recency), not embedding-based.** Don't
+  imply semantic/meaning-based retrieval in comments or docs you generate — if the task genuinely
+  needs free-text similarity search, pair `memorio.memory` (for lifecycle: confidence, TTL,
+  supersession) with a separate embedding store, don't fake it with `context()` alone.
+- **`memorio.logger` records the literal value written**, including tokens or PII, in
+  `getHistory()` / `exportLogs()`. Never enable it unconditionally on a production path that
+  touches sensitive data, and never wire `exportLogs()` output to analytics or error reporters
+  without redaction first.
+- **Nothing in `store`, `session`, `idb`, or `memory` is encrypted.** Don't store auth tokens or
+  regulated data in any of these layers without adding your own encryption — flag it in code
+  review comments if you see it happening.
+
+## React usage
+
+`useObserver` has two modes — pick deliberately, don't mix them by accident:
+
+```tsx
+// Auto-discovery: re-runs when any state path touched during the callback changes
+useObserver(() => { console.debug('counter:', state.counter) }, state.counter)
+
+// Explicit deps: only re-runs when the listed paths change
+useObserver(() => { console.debug('user:', state.user) }, [state.user])
+```
+
+`useObserver` is a thin bridge onto `observer` — it inherits the "unchecked path string" caveat
+above for any path passed in string form.
+
+## Cross-platform code
+
+Before calling `idb`, `sqlite`, or `devtools`, or before relying on `store`/`session` durability,
+check `memorio.getCapabilities()` rather than branching on `memorio.isNode()`/`isBrowser()` alone
+— capabilities can differ inside a single platform category (e.g. some edge runtimes expose
+`localStorage`, some don't). Generated code that assumes "browser == has IndexedDB" or
+"Node == no persistence at all" will be wrong on edge runtimes.
+
+## Testing
+
+When testing `memory` lifecycle behavior (supersession, TTL, confidence), assert on the *history*
+being preserved, not just the current `recall()` value — `update()` is documented to supersede,
+not overwrite, and a test that only checks the latest value won't catch a regression that
+silently starts overwriting instead.
+
+## Related examples
+
+See `examples/` in this repo for runnable reference implementations:
+`multi-tenant-context.ts`, `react-observer.tsx`, `semantic-memory.ts`,
+`sqlite-batched-writes.ts`, and `cross-platform-guards.ts`.

package/examples/basic.ts

@@ -0,0 +1,115 @@
+/**
+ * Memorio Basic Example
+ *
+ * This example shows the fundamental features of Memorio:
+ * - State management
+ * - Store (localStorage)
+ * - Session storage
+ * - Platform detection
+ *
+ * Run: npx ts-node examples/basic.ts
+ */
+
+import 'memorio'
+
+// ============================================
+// PLATFORM DETECTION
+// ============================================
+
+console.debug('=== Platform Detection ===')
+console.debug('Memorio version:', memorio.version)
+
+// Check platform
+if (memorio.isBrowser()) {
+  console.debug('Platform: Browser')
+} else if (memorio.isNode()) {
+  console.debug('Platform: Node.js')
+} else if (memorio.isDeno()) {
+  console.debug('Platform: Deno')
+} else if (memorio.isEdge()) {
+  console.debug('Platform: Edge Worker')
+}
+
+// Get capabilities
+const caps = memorio.getCapabilities()
+console.debug('Capabilities:', {
+  platform: caps.platform,
+  hasLocalStorage: caps.hasLocalStorage,
+  hasSessionStorage: caps.hasSessionStorage,
+  hasIndexedDB: caps.hasIndexedDB
+})
+
+// ============================================
+// STATE - In-memory reactive state
+// ============================================
+
+console.debug('\n=== State Management ===')
+
+// Set some state values
+state.name = 'Mario'
+state.age = 30
+state.isActive = true
+state.profile = {
+  email: 'mario@example.com',
+  avatar: 'https://example.com/mario.png'
+}
+
+// Get state values
+console.debug('Name:', state.name)
+console.debug('Age:', state.age)
+console.debug('Profile:', state.profile)
+
+// List all states
+console.debug('All states:', state.list)
+
+// ============================================
+// STORE - Persistent localStorage
+// ============================================
+
+console.debug('\n=== Store (Persistent Storage) ===')
+
+// Check persistence
+console.debug('Is persistent:', store.isPersistent) // true in browser, false in Node.js/Deno
+
+// Save to localStorage
+store.set('username', 'mario')
+store.set('preferences', { theme: 'dark', language: 'en' })
+store.set('lastLogin', Date.now())
+
+// Read from localStorage
+console.debug('Username:', store.get('username'))
+console.debug('Preferences:', store.get('preferences'))
+
+// Get storage size
+console.debug('Storage size:', store.size(), 'bytes')
+
+// ============================================
+// SESSION - Temporary session storage
+// ============================================
+
+console.debug('\n=== Session (Temporary Storage) ===')
+
+// Check persistence
+console.debug('Is persistent:', session.isPersistent) // true in browser, false in Node.js/Deno
+
+// Save session data (cleared when tab closes)
+session.set('token', 'abc123xyz')
+session.set('userId', 42)
+
+// Read session data
+console.debug('Token:', session.get('token'))
+console.debug('User ID:', session.get('userId'))
+
+// ============================================
+// CLEANUP
+// ============================================
+
+// Clear specific items
+store.remove('username')
+session.remove('token')
+
+// Clear all
+store.removeAll()
+session.removeAll()
+
+console.debug('\nExample complete!')

package/examples/browser-vanilla.html

@@ -0,0 +1,358 @@
+<!DOCTYPE html>
+<html lang="en">
+
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Memorio Vanilla JS Example</title>
+  <style>
+    /* Simple CSS */
+    body {
+      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+      max-width: 800px;
+      margin: 0 auto;
+      padding: 20px;
+      background: #f5f5f5;
+    }
+
+    .card {
+      background: white;
+      border-radius: 8px;
+      padding: 20px;
+      margin-bottom: 20px;
+      box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);
+    }
+
+    h1 {
+      color: #333;
+    }
+
+    h2 {
+      color: #666;
+      margin-top: 0;
+    }
+
+    button {
+      background: #007bff;
+      color: white;
+      border: none;
+      padding: 10px 20px;
+      border-radius: 4px;
+      cursor: pointer;
+      margin: 5px;
+    }
+
+    button:hover {
+      background: #0056b3;
+    }
+
+    button.danger {
+      background: #dc3545;
+    }
+
+    button.danger:hover {
+      background: #c82333;
+    }
+
+    button.success {
+      background: #28a745;
+    }
+
+    button.success:hover {
+      background: #218838;
+    }
+
+    input,
+    select {
+      padding: 8px;
+      border: 1px solid #ddd;
+      border-radius: 4px;
+      margin: 5px;
+    }
+
+    pre {
+      background: #f8f9fa;
+      padding: 10px;
+      border-radius: 4px;
+      overflow-x: auto;
+    }
+
+    .output {
+      background: #e9ecef;
+      padding: 10px;
+      border-radius: 4px;
+      font-family: monospace;
+      white-space: pre-wrap;
+    }
+
+    .grid {
+      display: grid;
+      grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
+      gap: 10px;
+    }
+
+    .stat {
+      background: #e7f3ff;
+      padding: 10px;
+      border-radius: 4px;
+      text-align: center;
+    }
+
+    .stat-value {
+      font-size: 24px;
+      font-weight: bold;
+      color: #007bff;
+    }
+
+    .stat-label {
+      font-size: 12px;
+      color: #666;
+    }
+  </style>
+</head>
+
+<body>
+  <h1>🧠 Memorio Vanilla JS Demo</h1>
+
+  <!-- State Section -->
+  <div class="card">
+    <h2>1. State (Reactive)</h2>
+    <p>Global reactive state - changes trigger UI updates automatically</p>
+
+    <div class="grid">
+      <div class="stat">
+        <div class="stat-value" id="counter">0</div>
+        <div class="stat-label">Counter</div>
+      </div>
+      <div class="stat">
+        <div class="stat-value" id="username">-</div>
+        <div class="stat-label">Username</div>
+      </div>
+      <div class="stat">
+        <div class="stat-value" id="theme">light</div>
+        <div class="stat-label">Theme</div>
+      </div>
+    </div>
+
+    <br>
+    <button onclick="state.counter++">Increment Counter</button>
+    <button onclick="state.counter--">Decrement</button>
+    <button onclick="state.counter = 0">Reset</button>
+
+    <h3>Set Username:</h3>
+    <input type="text" id="nameInput" placeholder="Enter name">
+    <button onclick="state.username = document.getElementById('nameInput').value">Set</button>
+
+    <h3>Theme:</h3>
+    <button onclick="state.theme = 'light'">Light</button>
+    <button onclick="state.theme = 'dark'">Dark</button>
+
+    <h3>All State:</h3>
+    <pre id="stateOutput" class="output"></pre>
+  </div>
+
+  <!-- Store Section -->
+  <div class="card">
+    <h2>2. Store (localStorage)</h2>
+    <p>Permanent storage - survives page refresh</p>
+    <p>Persistent: <span id="storePersistent">checking...</span></p>
+
+    <input type="text" id="storeKey" placeholder="Key">
+    <input type="text" id="storeValue" placeholder="Value">
+    <button
+      onclick="store.set(document.getElementById('storeKey').value, document.getElementById('storeValue').value)">Save</button>
+    <button
+      onclick="document.getElementById('storeOutput').textContent = JSON.stringify(store.get(document.getElementById('storeKey').value), null, 2)">Get</button>
+    <button class="danger" onclick="store.remove(document.getElementById('storeKey').value)">Delete</button>
+
+    <h3>All Store Data:</h3>
+    <pre id="storeOutput" class="output"></pre>
+  </div>
+
+  <!-- Session Section -->
+  <div class="card">
+    <h2>3. Session (sessionStorage)</h2>
+    <p>Temporary storage - cleared when tab closes</p>
+    <p>Persistent: <span id="sessionPersistent">checking...</span></p>
+
+    <input type="text" id="sessionKey" placeholder="Key">
+    <input type="text" id="sessionValue" placeholder="Value">
+    <button
+      onclick="session.set(document.getElementById('sessionKey').value, document.getElementById('sessionValue').value)">Save</button>
+    <button
+      onclick="document.getElementById('sessionOutput').textContent = JSON.stringify(session.get(document.getElementById('sessionKey').value), null, 2)">Get</button>
+    <button class="danger" onclick="session.remove(document.getElementById('sessionKey').value)">Delete</button>
+
+    <h3>All Session Data:</h3>
+    <pre id="sessionOutput" class="output"></pre>
+  </div>
+
+  <!-- Cache Section -->
+  <div class="card">
+    <h2>4. Cache (In-Memory)</h2>
+    <p>Temporary cache - cleared on refresh</p>
+
+    <input type="text" id="cacheKey" placeholder="Key">
+    <input type="text" id="cacheValue" placeholder="Value">
+    <button
+      onclick="cache.set(document.getElementById('cacheKey').value, document.getElementById('cacheValue').value)">Save</button>
+    <button
+      onclick="document.getElementById('cacheOutput').textContent = JSON.stringify(cache.get(document.getElementById('cacheKey').value), null, 2)">Get</button>
+    <button class="danger" onclick="cache.remove(document.getElementById('cacheKey').value)">Delete</button>
+
+    <h3>All Cache Data:</h3>
+    <pre id="cacheOutput" class="output"></pre>
+  </div>
+
+  <!-- Observer Section -->
+  <div class="card">
+    <h2>5. Observer (Auto-Reactive)</h2>
+    <p>Watch for state changes automatically</p>
+
+    <button class="success" id="startObserver">Start Observer</button>
+    <button class="danger" id="stopObserver">Stop Observer</button>
+    <button onclick="state.testValue = Math.random()">Trigger Change</button>
+
+    <h3>Observer Log:</h3>
+    <pre id="observerLog" class="output"></pre>
+  </div>
+
+  <!-- Platform Info -->
+  <div class="card">
+    <h2>6. Platform Info</h2>
+    <div id="platformInfo" class="output"></div>
+  </div>
+
+  <!-- Load Memorio -->
+  <script src="https://cdn.jsdelivr.net/npm/memorio/index.cjs"></script>
+
+  <script>
+    // ============================================
+    // MEMORIO VANILLA JS EXAMPLE
+    // ============================================
+
+    // 1. REACTIVE STATE
+    // -----------------
+
+    // Initialize state
+    state.counter = 0
+    state.username = 'Guest'
+    state.theme = 'light'
+    state.testValue = 0
+
+    // Update UI when state changes
+    function updateStateUI() {
+      document.getElementById('counter').textContent = state.counter
+      document.getElementById('username').textContent = state.username
+      document.getElementById('theme').textContent = state.theme
+      document.getElementById('stateOutput').textContent = JSON.stringify({
+        counter: state.counter,
+        username: state.username,
+        theme: state.theme,
+        testValue: state.testValue
+      }, null, 2)
+    }
+
+    // Use observer to react to changes
+    useObserver(() => {
+      updateStateUI()
+      document.body.className = state.theme
+    }, [state.counter, state.username, state.theme, state.testValue])
+
+    // 2. PERSISTENT STORE
+    // -------------------
+
+    // Check persistence
+    document.getElementById('storePersistent').textContent = store.isPersistent ? '✅ Yes (localStorage)' : '❌ No (memory)'
+
+    // Save sample data
+    store.set('visits', '0')
+    store.set('lastVisit', new Date().toISOString())
+
+    function updateStoreUI() {
+      document.getElementById('storeOutput').textContent = 'Visits: ' + store.get('visits') + '\nLast Visit: ' + store.get('lastVisit')
+    }
+    updateStoreUI()
+
+    // Increment visits
+    let visits = parseInt(store.get('visits') || '0')
+    store.set('visits', (visits + 1).toString())
+
+    // 3. SESSION STORAGE
+    // ------------------
+
+    document.getElementById('sessionPersistent').textContent = session.isPersistent ? '✅ Yes (sessionStorage)' : '❌ No (memory)'
+
+    session.set('pageViews', '0')
+
+    function updateSessionUI() {
+      document.getElementById('sessionOutput').textContent = 'Page Views: ' + session.get('pageViews')
+    }
+    updateSessionUI()
+
+    // Increment page views
+    let pageViews = parseInt(session.get('pageViews') || '0')
+    session.set('pageViews', (pageViews + 1).toString())
+
+    // 4. CACHE (In-Memory)
+    // --------------------
+
+    cache.set('tempData', { computed: true, timestamp: Date.now() })
+
+    function updateCacheUI() {
+      document.getElementById('cacheOutput').textContent = JSON.stringify(cache.get('tempData'), null, 2)
+    }
+    updateCacheUI()
+
+    // 5. OBSERVER
+    // -----------
+
+    let observerActive = false
+    const logEl = document.getElementById('observerLog')
+
+    document.getElementById('startObserver').onclick = () => {
+      observerActive = true
+      logEl.textContent += 'Observer started!\n'
+    }
+
+    document.getElementById('stopObserver').onclick = () => {
+      observerActive = false
+      logEl.textContent += 'Observer stopped!\n'
+    }
+
+    // This creates a persistent observer
+    useObserver((newVal, oldVal) => {
+      if (observerActive) {
+        logEl.textContent += `Changed: ${oldVal} → ${newVal}\n`
+        logEl.scrollTop = logEl.scrollHeight
+      }
+    }, [state.testValue])
+
+    // 6. PLATFORM INFO
+    // ----------------
+
+    const platformInfo = document.getElementById('platformInfo')
+    platformInfo.textContent = `
+Platform Detection:
+-----------------
+Browser: ${memorio.isBrowser() ? '✅' : '❌'}
+Node.js: ${memorio.isNode() ? '✅' : '❌'}
+Deno: ${memorio.isDeno() ? '✅' : '❌'}
+Edge: ${memorio.isEdge() ? '✅' : '❌'}
+
+Capabilities:
+-------------
+localStorage: ${memorio.getCapabilities().hasLocalStorage ? '✅' : '❌'}
+sessionStorage: ${memorio.getCapabilities().hasSessionStorage ? '✅' : '❌'}
+IndexedDB: ${memorio.getCapabilities().hasIndexedDB ? '✅' : '❌'}
+
+Session ID: ${memorio.getCapabilities().sessionId.substring(0, 8)}...
+    `.trim()
+
+    // Log welcome
+    console.debug('🧠 Memorio loaded!')
+    console.debug('Platform:', memorio.getCapabilities().platform)
+  </script>
+</body>
+
+</html>

package/examples/cache.ts

@@ -0,0 +1,72 @@
+/**
+ * Memorio Cache Example
+ *
+ * This example demonstrates the cache module for in-memory storage.
+ * Cache is perfect for temporary data that doesn't need persistence.
+ *
+ * Run: npx ts-node examples/cache.ts
+ */
+
+import 'memorio'
+
+// ============================================
+// BASIC CACHE OPERATIONS
+// ============================================
+
+// Set values
+cache.set('username', 'Mario')
+cache.set('score', 1500)
+cache.set('player', { name: 'Mario', level: 5 })
+
+// Get values
+console.debug('Username:', cache.get('username'))
+console.debug('Score:', cache.get('score'))
+console.debug('Player:', cache.get('player'))
+
+// Direct property access
+cache.tempData = 'Hello'
+console.debug('Temp data:', cache.tempData)
+
+// ============================================
+// CACHE WITH OBJECTS
+// ============================================
+
+// Store complex objects
+cache.set('gameState', {
+  level: 3,
+  score: 2500,
+  inventory: ['sword', 'shield', 'potion'],
+  position: { x: 100, y: 200 }
+})
+
+const gameState = cache.get('gameState')
+console.debug('Game level:', gameState?.level)
+console.debug('Inventory:', gameState?.inventory)
+
+// ============================================
+// CACHE SIZE
+// ============================================
+
+// Add multiple items
+for (let i = 0; i < 10; i++) {
+  cache.set(`item_${i}`, { id: i, data: `item-${i}` })
+}
+
+console.debug('Cache keys:', Object.keys(cache))
+
+// ============================================
+// CLEANUP
+// ============================================
+
+// Remove single item
+cache.remove('username')
+
+// Clear all cache
+cache.removeAll()
+
+// Or use clearAll alias
+// cache.clearAll()
+
+console.debug('Cache after clear:', cache.get('score'))
+
+console.debug('Cache example complete!')