memorio 5.1.3 → 5.2.0

package/examples/agent-memory-demo.ts

@@ -0,0 +1,140 @@
+/**
+ * agent-memory-demo.ts
+ *
+ * Scenario: An AI agent that remembers user preferences across conversations.
+ *
+ * Demonstrates:
+ * - Conversation 1: agent remembers a user preference
+ * - Conversation 2: agent recalls the preference
+ * - Context generation: agent gets relevant context for a query
+ * - Temporal history: agent queries how state evolved
+ * - Provenance: agent explains why it knows what it knows
+ */
+
+import { createAgentMemory } from '../../agent'
+
+async function main() {
+  const agent = createAgentMemory('support-agent')
+
+  // Clear any prior state for a clean demo
+  await agent.clear()
+
+  // ─── Conversation 1 ───────────────────────────────────────────
+  console.log('=== Conversation 1 ===')
+  console.log('User: "I prefer PostgreSQL for databases."')
+
+  // Agent remembers the preference with metadata
+  await agent.remember('user.pref.database', 'PostgreSQL', {
+    type: 'preference',
+    confidence: 0.91,
+    source: 'conversation-1',
+    tags: ['database', 'infrastructure'],
+    ttl: null // persistent memory
+  })
+
+  console.log('Agent: "Got it. PostgreSQL it is."')
+  console.log('')
+
+  // ─── Conversation 2 ─────────────────────────────────────────
+  console.log('=== Conversation 2 (later) ===')
+  console.log('User: "What database did I say I preferred?"')
+
+  // Agent recalls the memory
+  const preference = await agent.recall('user.pref.database')
+  console.log(`Agent: "You said ${preference?.value}."`)
+  console.log('')
+
+  // ─── Context Generation ─────────────────────────────────────
+  console.log('=== Context for Agent Query ===')
+  console.log('User: "What databases do you know about for this project?"')
+
+  const context = await agent.context({
+    tags: ['database'],
+    types: ['preference', 'decision', 'fact'],
+    minConfidence: 0.5,
+    maxEntries: 10
+  })
+
+  console.log('Agent Context (relevant memories):')
+  for (const entry of context) {
+    console.log(`  - ${entry.key}: ${entry.value}`)
+    console.log(`    type: ${entry.type}, confidence: ${entry.confidence}, age: ${Math.round(entry.age / 1000)}s`)
+    console.log(`    tags: ${entry.tags.join(', ')}`)
+  }
+  console.log('')
+
+  // ─── Memory Evolution (supersedence) ─────────────────────────
+  console.log('=== Memory Evolution ===')
+
+  // Update the preference (creates superseded entries)
+  await agent.remember('user.pref.database', 'MySQL', {
+    type: 'preference',
+    confidence: 0.85,
+    source: 'conversation-3',
+    tags: ['database', 'infrastructure']
+  })
+
+  // Small delay to ensure unique timestamps for superseded entries
+  await new Promise(resolve => setTimeout(resolve, 5))
+
+  await agent.remember('user.pref.database', 'SQLite', {
+    type: 'preference',
+    confidence: 0.92,
+    source: 'conversation-4',
+    tags: ['database', 'infrastructure']
+  })
+
+  // Query the latest state
+  const latest = await agent.recall('user.pref.database')
+  console.log(`Latest preference: ${latest?.value} (confidence: ${latest?.confidence})`)
+
+  // Query all entries including superseded
+  const mem = (globalThis as any).memorio.memory
+  const allEntries = await mem._loadAll()
+  const keyHistory = allEntries
+    .filter((e: any) => e.key === `agent:support-agent:user.pref.database`)
+    .sort((a: any, b: any) => a.createdAt - b.createdAt)
+
+  console.log('History of this decision:')
+  for (const entry of keyHistory) {
+    const statusIcon = entry.status === 'superseded' ? '  (superseded)' : '  (current)'
+    console.log(`  - ${new Date(entry.createdAt).toISOString()}: ${entry.value}${statusIcon}`)
+    console.log(`    source: ${entry.source}, confidence: ${entry.confidence}`)
+  }
+  console.log('')
+
+  // ─── Provenance / Explain ───────────────────────────────────
+  console.log('=== Provenance ===')
+  console.log('User: "Why do you know SQLite?"')
+
+  const current = await agent.recall('user.pref.database')
+  console.log(`Agent: "I know SQLite because:"`)
+  console.log(`  - Source: ${current?.source}`)
+  console.log(`  - Confidence: ${current?.confidence}`)
+  console.log(`  - Stored at: ${new Date(current!.createdAt).toISOString()}`)
+  console.log(`  - Tags: ${current?.tags.join(', ')}`)
+  console.log('')
+
+  // Show why we know about PostgreSQL (even though it was superseded)
+  const postgresqlEntry = keyHistory.find((e: any) => e.value === 'PostgreSQL')
+  if (postgresqlEntry) {
+    console.log(`Agent: "PostgreSQL was previously known because:"`)
+    console.log(`  - Source: ${postgresqlEntry.source}`)
+    console.log(`  - Confidence: ${postgresqlEntry.confidence}`)
+    console.log(`  - Status: ${postgresqlEntry.status}`)
+    console.log(`  - Stored at: ${new Date(postgresqlEntry.createdAt).toISOString()}`)
+    console.log(`  - Tags: ${postgresqlEntry.tags.join(', ')}`)
+  }
+  console.log('')
+
+  // ─── Stats ─────────────────────────────────────────────────
+  console.log('=== Memory Stats ===')
+  const stats = await agent.stats()
+  console.log(`Total memories: ${stats.total}`)
+  console.log(`By scope:`, stats.byScope)
+  console.log(`By type:`, stats.byType)
+
+  console.log('\n=== Demo Complete ===')
+}
+
+main().catch(console.error)

package/examples/sqlite-batched-writes.ts

@@ -1,60 +1,60 @@
-/**
- * sqlite-batched-writes.ts
- *
- * Scenario: importing or writing many rows into memorio's sqlite layer.
- *
- * With persistence enabled, each write is recorded in an append-only journal
- * (incremental). Periodic checkpoints — every 50 operations or 250 ms of
- * write-idle — take a full database snapshot. Calling `flush()` inside a
- * per-row loop triggers a checkpoint on every iteration, which is expensive.
- */
-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 trigger a full checkpoint 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, flush once after the batch. Writes are
-  // journaled incrementally (cheap); the checkpoint (full snapshot) happens
-  // once at the end.
-  for (const user of users) {
-    await memorio.sqlite.query.run(
-      'app',
-      `INSERT INTO users (id, name, role) VALUES (?, ?, ?)`,
-      [user.id, user.name, user.role]
-    )
-  }
-
-  // Flush 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 journal and checkpoint overhead altogether.
+/**
+ * sqlite-batched-writes.ts
+ *
+ * Scenario: importing or writing many rows into memorio's sqlite layer.
+ *
+ * With persistence enabled, each write is recorded in an append-only journal
+ * (incremental). Periodic checkpoints - every 50 operations or 250 ms of
+ * write-idle - take a full database snapshot. Calling `flush()` inside a
+ * per-row loop triggers a checkpoint on every iteration, which is expensive.
+ */
+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 trigger a full checkpoint 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, flush once after the batch. Writes are
+  // journaled incrementally (cheap); the checkpoint (full snapshot) happens
+  // once at the end.
+  for (const user of users) {
+    await memorio.sqlite.query.run(
+      'app',
+      `INSERT INTO users (id, name, role) VALUES (?, ?, ?)`,
+      [user.id, user.name, user.role]
+    )
+  }
+
+  // Flush 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 journal and checkpoint overhead altogether.

package/examples/sync.ts

@@ -1,90 +1,90 @@
-/**
- * sync.ts
- *
- * Scenario: an app using `memorio.memory` that wants to survive being
- * offline (data is born local, in the journal, and always readable) and
- * mirror itself to a backend when a connection is available.
- *
- * The cloud is a transport/persistence provider here, never the source of
- * truth - sync mirrors the local journal, it doesn't replace it. Provide
- * your own `SyncProvider`; memorio doesn't ship one.
- */
-import { memorio } from 'memorio'
-
-interface MemoryEntry {
-  key: string
-  value: unknown
-  confidence?: number
-  source?: string
-  scope?: 'device' | 'user' | 'shared'
-}
-
-interface SyncProvider {
-  push(ops: MemoryEntry[]): Promise<{ synced: string[]; conflicts?: string[]; error?: string }>
-  pull?(since?: number): Promise<MemoryEntry[]>
-  resolve?(op: MemoryEntry): Promise<'local' | 'remote' | 'merge'>
-}
-
-const backendProvider: SyncProvider = {
-  push: ops =>
-    fetch('/api/sync', {
-      method: 'POST',
-      body: JSON.stringify(ops),
-      headers: { 'Content-Type': 'application/json' }
-    }).then(r => r.json()),
-
-  pull: since => fetch(`/api/sync?since=${since ?? 0}`).then(r => r.json()),
-
-  // Higher-confidence entry wins locally; for 'shared' scope the provider
-  // (i.e. your backend) makes the final call instead.
-  resolve: async op => (op.confidence ?? 0) >= 0.8 ? 'local' : 'remote'
-}
-
-export async function configureSync(namespace: string) {
-  // `scope: 'device'` data never syncs (sticky to this device) - only
-  // 'user' and 'shared' scoped entries flow through the provider below.
-  memorio.memory.configure({
-    namespace, // e.g. `user:123:device:abc` - partitions the local journal
-    provider: backendProvider,
-    auto: true // auto-replay the journal on focus/online (default: true)
-  })
-
-  await memorio.memory.ready
-}
-
-export async function rememberAndSync(key: string, value: unknown) {
-  // Local-first: this resolves immediately from the local store, no
-  // network round-trip required.
-  await memorio.memory.remember(key, value, { scope: 'user', source: 'app' })
-}
-
-// ---------------------------------------------------------------------------
-// The journal: the durable op log that drives cloud reconciliation
-// ---------------------------------------------------------------------------
-
-export async function inspectPendingOps() {
-  const pending = await memorio.memory.journal.pending()
-  console.debug('Operations waiting to sync:', pending)
-  return pending
-}
-
-export async function forceReplay() {
-  // Pushes pending() to the provider, marks synced entries, and pulls if
-  // the provider implements it. Normally triggered automatically (`auto:
-  // true`) on focus/online - call this manually to sync on demand instead.
-  const ack = await memorio.memory.journal.replay()
-  console.debug('Sync result:', ack)
-  return ack
-}
-
-export async function resetJournal() {
-  // Wipes the current namespace's journal only - does not touch the
-  // memory entries themselves, just the pending sync log.
-  await memorio.memory.journal.clear()
-}
-
-// Usage:
-// await configureSync('user:123:device:abc')
-// await rememberAndSync('user.language', 'Italian')
-// await inspectPendingOps()
-// await forceReplay()
+/**
+ * sync.ts
+ *
+ * Scenario: an app using `memorio.memory` that wants to survive being
+ * offline (data is born local, in the journal, and always readable) and
+ * mirror itself to a backend when a connection is available.
+ *
+ * The cloud is a transport/persistence provider here, never the source of
+ * truth - sync mirrors the local journal, it doesn't replace it. Provide
+ * your own `SyncProvider`; memorio doesn't ship one.
+ */
+import { memorio } from 'memorio'
+
+interface MemoryEntry {
+  key: string
+  value: unknown
+  confidence?: number
+  source?: string
+  scope?: 'hot' | 'session' | 'local' | 'durable'
+}
+
+interface SyncProvider {
+  push(ops: MemoryEntry[]): Promise<{ synced: string[]; conflicts?: string[]; error?: string }>
+  pull?(since?: number): Promise<MemoryEntry[]>
+  resolveConflict?(local: MemoryEntry, remote: MemoryEntry): Promise<'local' | 'remote' | 'merge'>
+}
+
+const backendProvider: SyncProvider = {
+  push: ops =>
+    fetch('/api/sync', {
+      method: 'POST',
+      body: JSON.stringify(ops),
+      headers: { 'Content-Type': 'application/json' }
+    }).then(r => r.json()),
+
+  pull: since => fetch(`/api/sync?since=${since ?? 0}`).then(r => r.json()),
+
+  // Higher-confidence entry wins locally; for 'shared' scope the provider
+  // (i.e. your backend) makes the final call instead.
+  resolveConflict: async (local, remote) => (local.confidence ?? 0) >= 0.8 ? 'local' : 'remote'
+}
+
+export async function configureSync(namespace: string) {
+  // Namespace partitions the journal; only entries written while sync is
+  // configured (via configure()) flow through the provider below.
+  memorio.memory.configure({
+    namespace, // e.g. `user:123:device:abc` - partitions the local journal
+    provider: backendProvider,
+    auto: true // auto-replay the journal on focus/online (default: true)
+  })
+
+  await memorio.memory.journal.status() // substrate is 'store'; journal is ready
+}
+
+export async function rememberAndSync(key: string, value: unknown) {
+  // Local-first: this resolves immediately from the local store, no
+  // network round-trip required.
+  await memorio.memory.remember(key, value, { scope: 'local', source: 'app' })
+}
+
+// ---------------------------------------------------------------------------
+// The journal: the durable op log that drives cloud reconciliation
+// ---------------------------------------------------------------------------
+
+export async function inspectPendingOps() {
+  const pending = await memorio.memory.journal.pending()
+  console.debug('Operations waiting to sync:', pending)
+  return pending
+}
+
+export async function forceReplay() {
+  // Pushes pending() to the provider, marks synced entries, and pulls if
+  // the provider implements it. Normally triggered automatically (`auto:
+  // true`) on focus/online - call this manually to sync on demand instead.
+  const ack = await memorio.memory.journal.replay()
+  console.debug('Sync result:', ack)
+  return ack
+}
+
+export async function resetJournal() {
+  // Wipes the current namespace's journal only - does not touch the
+  // memory entries themselves, just the pending sync log.
+  await memorio.memory.journal.clear()
+}
+
+// Usage:
+// await configureSync('user:123:device:abc')
+// await rememberAndSync('user.language', 'Italian')
+// await inspectPendingOps()
+// await forceReplay()

package/examples/useObserver.tsx

@@ -58,8 +58,8 @@ function AutoDiscovery() {
 function SyncedComponent() {
   const [localData, setLocalData] = useState(null)
 
-  useObserver((newValue: unknown) => {
-    setLocalData(newValue)
+  useObserver(() => {
+    setLocalData(state.data)
   }, [state.data])
 
   return <div>{localData}</div>