memorio 4.9.31 → 5.0.0

package/examples/react-observer.tsx

@@ -1,63 +1,63 @@
-/**
- * react-observer.tsx
- *
- * Scenario: a React component reading reactive `state`. Shows both
- * `useObserver` modes and when to prefer each, plus `typed<T>()` +
- * `registerSchema()` for the paths you don't want to fail silently on a
- * typo or a later rename.
- */
-import 'memorio'
-import { useReducer } from 'react'
-
-interface AppState {
-  counter: number
-  user: { name: string; email: string }
-}
-
-// Compile-time safety: same Proxy as the global `state`, no duplicated store.
-const app = memorio.typed<AppState>()
-
-// Runtime safety: reject writes that don't match the shape, independent of
-// whatever calls it (including code you didn't write).
-memorio.registerSchema('user', {
-  type: 'object',
-  required: ['name', 'email'],
-  properties: {
-    name: { type: 'string', min: 1 },
-    email: { type: 'string', pattern: /^[^@]+@[^@]+$/ },
-  },
-})
-
-export function Counter() {
-  const [, forceUpdate] = useReducer((x: number) => x + 1, 0)
-
-  // Auto-discovery mode: re-runs when any state path *touched inside the
-  // callback* changes. Convenient, but re-runs on anything you read there -
-  // don't reach for it in a callback that reads many unrelated paths.
-  useObserver(() => {
-    forceUpdate()
-  }, state.counter)
-
-  return (
-    <div>
-      <span>Count: {app.counter}</span>
-      <button onClick={() => { app.counter += 1 }}>+1</button>
-    </div>
-  )
-}
-
-export function UserBadge() {
-  const [, forceUpdate] = useReducer((x: number) => x + 1, 0)
-
-  // Explicit deps mode: only re-runs when the listed path(s) change - use
-  // this when you want precise control instead of auto-discovery.
-  useObserver(() => {
-    forceUpdate()
-  }, [state.user])
-
-  return <span>{app.user?.name ?? 'Guest'}</span>
-}
-
-// Rejected at write time by the schema registered above:
-// app.user = { name: 'Sara' }              // ❌ missing "email"
-// app.user = { name: 'Sara', email: 'x@y.com' }  // ✅
+/**
+ * react-observer.tsx
+ *
+ * Scenario: a React component reading reactive `state`. Shows both
+ * `useObserver` modes and when to prefer each, plus `typed<T>()` +
+ * `registerSchema()` for the paths you don't want to fail silently on a
+ * typo or a later rename.
+ */
+import { memorio, state, useObserver } from 'memorio'
+import { useReducer } from 'react'
+
+interface AppState {
+  counter: number
+  user: { name: string; email: string }
+}
+
+// Compile-time safety: same Proxy as the global `state`, no duplicated store.
+const app = memorio.typed<AppState>()
+
+// Runtime safety: reject writes that don't match the shape, independent of
+// whatever calls it (including code you didn't write).
+memorio.registerSchema('user', {
+  type: 'object',
+  required: ['name', 'email'],
+  properties: {
+    name: { type: 'string', min: 1 },
+    email: { type: 'string', pattern: /^[^@]+@[^@]+$/ },
+  },
+})
+
+export function Counter() {
+  const [, forceUpdate] = useReducer((x: number) => x + 1, 0)
+
+  // Auto-discovery mode: re-runs when any state path *touched inside the
+  // callback* changes. Convenient, but re-runs on anything you read there -
+  // don't reach for it in a callback that reads many unrelated paths.
+  useObserver(() => {
+    forceUpdate()
+  }, state.counter)
+
+  return (
+    <div>
+      <span>Count: {app.counter}</span>
+      <button onClick={() => { app.counter += 1 }}>+1</button>
+    </div>
+  )
+}
+
+export function UserBadge() {
+  const [, forceUpdate] = useReducer((x: number) => x + 1, 0)
+
+  // Explicit deps mode: only re-runs when the listed path(s) change - use
+  // this when you want precise control instead of auto-discovery.
+  useObserver(() => {
+    forceUpdate()
+  }, [state.user])
+
+  return <span>{app.user?.name ?? 'Guest'}</span>
+}
+
+// Rejected at write time by the schema registered above:
+// app.user = { name: 'Sara' }              // ❌ missing "email"
+// app.user = { name: 'Sara', email: 'x@y.com' }  // ✅

package/examples/semantic-memory.ts

@@ -1,60 +1,60 @@
-/**
- * semantic-memory.ts
- *
- * Scenario: an LLM-backed app that needs to remember facts about a user
- * with confidence, source, and expiry - and later retrieve only what's
- * relevant to the current task.
- *
- * Important: `memory.context()` ranks by tags/type/confidence/recency.
- * It is NOT embedding-based semantic search - don't build a feature that
- * assumes free-text meaning-based retrieval on top of this alone.
- */
-import { memorio } from 'memorio'
-
-export async function rememberPreference(
-  key: string,
-  value: unknown,
-  opts: { confidence: number; source: string; tags: string[] }
-) {
-  await memorio.memory.remember(key, value, {
-    type: 'preference',
-    scope: 'local',
-    ...opts,
-  })
-}
-
-export async function correctPreference(key: string, newValue: unknown, confidence: number) {
-  // update() supersedes, it doesn't overwrite - the old entry becomes
-  // status: 'superseded' and stays queryable for history/audit purposes.
-  await memorio.memory.update(key, newValue, { confidence })
-}
-
-export async function getRelevantContext(tags: string[]) {
-  // This is rule-based retrieval, not semantic similarity search. It's the
-  // right tool for "give me what's tagged/confident/recent enough," not for
-  // "find the memory that means the same thing as this new sentence."
-  return memorio.memory.context({
-    tags,
-    types: ['preference', 'decision'],
-    minConfidence: 0.7,
-    maxEntries: 10,
-  })
-}
-
-// If the task genuinely needs meaning-based retrieval over free text (e.g.
-// "find prior notes about a similar problem" rather than "find notes tagged
-// X with confidence > Y"), pair this with a dedicated embedding store for
-// the similarity search, and keep using memorio.memory for the lifecycle
-// metadata (confidence, TTL, supersession) on top of whatever it finds -
-// don't simulate similarity search with context() alone.
-
-// Usage:
-// await rememberPreference('user.language', 'Italian', {
-//   confidence: 0.92,
-//   source: 'conversation',
-//   tags: ['user', 'ui'],
-// })
-//
-// await correctPreference('user.language', 'English', 0.95)
-//
-// const ctx = await getRelevantContext(['user'])
+/**
+ * semantic-memory.ts
+ *
+ * Scenario: an LLM-backed app that needs to remember facts about a user
+ * with confidence, source, and expiry - and later retrieve only what's
+ * relevant to the current task.
+ *
+ * Important: `memory.context()` ranks by tags/type/confidence/recency.
+ * It is NOT embedding-based semantic search - don't build a feature that
+ * assumes free-text meaning-based retrieval on top of this alone.
+ */
+import { memorio } from 'memorio'
+
+export async function rememberPreference(
+  key: string,
+  value: unknown,
+  opts: { confidence: number; source: string; tags: string[] }
+) {
+  await memorio.memory.remember(key, value, {
+    type: 'preference',
+    scope: 'local',
+    ...opts,
+  })
+}
+
+export async function correctPreference(key: string, newValue: unknown, confidence: number) {
+  // update() supersedes, it doesn't overwrite - the old entry becomes
+  // status: 'superseded' and stays queryable for history/audit purposes.
+  await memorio.memory.update(key, newValue, { confidence })
+}
+
+export async function getRelevantContext(tags: string[]) {
+  // This is rule-based retrieval, not semantic similarity search. It's the
+  // right tool for "give me what's tagged/confident/recent enough," not for
+  // "find the memory that means the same thing as this new sentence."
+  return memorio.memory.context({
+    tags,
+    types: ['preference', 'decision'],
+    minConfidence: 0.7,
+    maxEntries: 10,
+  })
+}
+
+// If the task genuinely needs meaning-based retrieval over free text (e.g.
+// "find prior notes about a similar problem" rather than "find notes tagged
+// X with confidence > Y"), pair this with a dedicated embedding store for
+// the similarity search, and keep using memorio.memory for the lifecycle
+// metadata (confidence, TTL, supersession) on top of whatever it finds -
+// don't simulate similarity search with context() alone.
+
+// Usage:
+// await rememberPreference('user.language', 'Italian', {
+//   confidence: 0.92,
+//   source: 'conversation',
+//   tags: ['user', 'ui'],
+// })
+//
+// await correctPreference('user.language', 'English', 0.95)
+//
+// const ctx = await getRelevantContext(['user'])

package/examples/session-advanced.ts

@@ -1,91 +1,91 @@
-/**
- * Memorio Session Advanced Example
- *
- * This example shows advanced session (sessionStorage) operations.
- * Session data is cleared when the browser tab closes.
- *
- * Run: npx ts-node examples/session-advanced.ts
- */
-
-import 'memorio'
-
-// ============================================
-// CHECK PERSISTENCE
-// ============================================
-
-console.debug('=== Session Persistence Check ===')
-console.debug('Is persistent (survives tab close):', session.isPersistent)
-// In browser: true (sessionStorage)
-// In Node.js/Deno: false (memory fallback)
-
-if (!session.isPersistent) {
-  console.debug('⚠️ Warning: Using in-memory storage. Data will be lost on process restart!')
-}
-
-// ============================================
-// AUTHENTICATION
-// ============================================
-
-// Store auth token (temporary - cleared when tab closes)
-session.set('authToken', 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...')
-session.set('userId', 12345)
-
-// Check if user is logged in
-const token = session.get('authToken')
-if (token) {
-  console.debug('User is logged in, token:', token.substring(0, 20) + '...')
-}
-
-// ============================================
-// FORM PROGRESS
-// ============================================
-
-// Save form draft
-session.set('formDraft', {
-  name: 'Mario',
-  email: 'mario@example.com',
-  message: 'Hello world!'
-})
-
-// Restore on page refresh
-const draft = session.get('formDraft')
-if (draft) {
-  console.debug('Restored draft:', draft)
-}
-
-// ============================================
-// SHOPPING CART
-// ============================================
-
-// Store cart items (temporary)
-session.set('cart', [
-  { id: 1, name: 'Super Mushroom', price: 99, qty: 2 },
-  { id: 2, name: 'Fire Flower', price: 199, qty: 1 }
-])
-
-// Calculate total
-const cart = session.get('cart') || []
-const total = cart.reduce((sum, item) => sum + (item.price * item.qty), 0)
-console.debug('Cart total:', total)
-
-// ============================================
-// SESSION SIZE
-// ============================================
-
-// Get session storage size
-console.debug('Session size:', session.size(), 'kilobytes')
-
-// ============================================
-// CLEANUP
-// ============================================
-
-// Remove specific item
-session.remove('formDraft')
-
-// Clear all session data (logout)
-// session.removeAll()
-
-// Or use alias
-// session.clearAll()
-
-console.debug('Session advanced example complete!')
+/**
+ * Memorio Session Advanced Example
+ *
+ * This example shows advanced session (sessionStorage) operations.
+ * Session data is cleared when the browser tab closes.
+ *
+ * Run: npx ts-node examples/session-advanced.ts
+ */
+
+import { session } from 'memorio'
+
+// ============================================
+// CHECK PERSISTENCE
+// ============================================
+
+console.debug('=== Session Persistence Check ===')
+console.debug('Is persistent (survives tab close):', session.isPersistent)
+// In browser: true (sessionStorage)
+// In Node.js/Deno: false (memory fallback)
+
+if (!session.isPersistent) {
+  console.debug('⚠️ Warning: Using in-memory storage. Data will be lost on process restart!')
+}
+
+// ============================================
+// AUTHENTICATION
+// ============================================
+
+// Store auth token (temporary - cleared when tab closes)
+session.set('authToken', 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...')
+session.set('userId', 12345)
+
+// Check if user is logged in
+const token = session.get('authToken')
+if (token) {
+  console.debug('User is logged in, token:', token.substring(0, 20) + '...')
+}
+
+// ============================================
+// FORM PROGRESS
+// ============================================
+
+// Save form draft
+session.set('formDraft', {
+  name: 'Mario',
+  email: 'mario@example.com',
+  message: 'Hello world!'
+})
+
+// Restore on page refresh
+const draft = session.get('formDraft')
+if (draft) {
+  console.debug('Restored draft:', draft)
+}
+
+// ============================================
+// SHOPPING CART
+// ============================================
+
+// Store cart items (temporary)
+session.set('cart', [
+  { id: 1, name: 'Super Mushroom', price: 99, qty: 2 },
+  { id: 2, name: 'Fire Flower', price: 199, qty: 1 }
+])
+
+// Calculate total
+const cart = session.get('cart') || []
+const total = cart.reduce((sum, item) => sum + (item.price * item.qty), 0)
+console.debug('Cart total:', total)
+
+// ============================================
+// SESSION SIZE
+// ============================================
+
+// Get session storage size
+console.debug('Session size:', session.size(), 'kilobytes')
+
+// ============================================
+// CLEANUP
+// ============================================
+
+// Remove specific item
+session.remove('formDraft')
+
+// Clear all session data (logout)
+// session.removeAll()
+
+// Or use alias
+// session.clearAll()
+
+console.debug('Session advanced example complete!')

package/examples/sqlite-batched-writes.ts

@@ -1,57 +1,57 @@
-/**
- * sqlite-batched-writes.ts
- *
- * Scenario: importing or writing many rows into memorio's sqlite layer.
- *
- * Persistence there serializes the ENTIRE database on every flush - not
- * incremental. Calling a persisting write inside a per-row loop is the
- * single most common way to accidentally make this layer slow.
- */
-import { memorio } from 'memorio'
-
-interface UserRow {
-  id: number
-  name: string
-  role: string
-}
-
-export async function importUsers(users: UserRow[]) {
-  await memorio.sqlite.ready
-  await memorio.sqlite.db.create('app', { persistence: true })
-
-  await memorio.sqlite.query.run(
-    'app',
-    `CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT NOT NULL, role TEXT)`
-  )
-
-  // Bad: this would serialize the whole DB after every single insert.
-  //
-  // for (const user of users) {
-  //   await memorio.sqlite.query.run('app', 'INSERT INTO users ...', [...])
-  //   await memorio.sqlite.db.flush('app') // <- don't do this per row
-  // }
-
-  // Good: run every insert first, persist once after the batch.
-  for (const user of users) {
-    await memorio.sqlite.query.run(
-      'app',
-      `INSERT INTO users (id, name, role) VALUES (?, ?, ?)`,
-      [user.id, user.name, user.role]
-    )
-  }
-
-  // Persist explicitly, once, after the whole batch - check the installed
-  // version's API for the exact flush/persist call name if it differs from
-  // automatic persistence-on-close.
-  const admins = await memorio.sqlite.query.select(
-    'app',
-    `SELECT * FROM users WHERE role = ?`,
-    ['admin']
-  )
-
-  return admins
-}
-
-// For read-heavy or scratch-space use where durability doesn't matter,
-// skip { persistence: true } entirely - sqlite runs in memory by default,
-// which avoids the serialize cost altogether.
+/**
+ * sqlite-batched-writes.ts
+ *
+ * Scenario: importing or writing many rows into memorio's sqlite layer.
+ *
+ * Persistence there serializes the ENTIRE database on every flush - not
+ * incremental. Calling a persisting write inside a per-row loop is the
+ * single most common way to accidentally make this layer slow.
+ */
+import { memorio } from 'memorio'
+
+interface UserRow {
+  id: number
+  name: string
+  role: string
+}
+
+export async function importUsers(users: UserRow[]) {
+  await memorio.sqlite.ready
+  await memorio.sqlite.db.create('app', { persistence: true })
+
+  await memorio.sqlite.query.run(
+    'app',
+    `CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT NOT NULL, role TEXT)`
+  )
+
+  // Bad: this would serialize the whole DB after every single insert.
+  //
+  // for (const user of users) {
+  //   await memorio.sqlite.query.run('app', 'INSERT INTO users ...', [...])
+  //   await memorio.sqlite.db.flush('app') // <- don't do this per row
+  // }
+
+  // Good: run every insert first, persist once after the batch.
+  for (const user of users) {
+    await memorio.sqlite.query.run(
+      'app',
+      `INSERT INTO users (id, name, role) VALUES (?, ?, ?)`,
+      [user.id, user.name, user.role]
+    )
+  }
+
+  // Persist explicitly, once, after the whole batch - check the installed
+  // version's API for the exact flush/persist call name if it differs from
+  // automatic persistence-on-close.
+  const admins = await memorio.sqlite.query.select(
+    'app',
+    `SELECT * FROM users WHERE role = ?`,
+    ['admin']
+  )
+
+  return admins
+}
+
+// For read-heavy or scratch-space use where durability doesn't matter,
+// skip { persistence: true } entirely - sqlite runs in memory by default,
+// which avoids the serialize cost altogether.