memorio 4.7.1 → 4.8.0

package/markdown/SYNC.md

@@ -0,0 +1,170 @@
+# Synchronization & Cloud (optional)
+
+`memorio.memory` is **local-first**. Data is created and served from the device;
+the cloud is only ever a **transport/persistence provider**, never the source of
+truth. Enabling sync does not replace local storage — it *mirrors* it.
+
+```
+                    memorio
+                       │
+              ┌────────┴────────┐
+              │   Memory Engine │
+              └────────┬────────┘
+          ┌────────────┼────────────┐
+          ▼            ▼            ▼
+        local      SQLite         cloud
+        memory     durable        sync
+```
+
+## 1. The rule: the data is born local
+
+```ts
+memorio.memory.remember('user.language', 'Italian', { scope: 'local' })
+//        ↓ local first
+//   store / sessionStorage / IndexedDB / sql.js
+//        ↓ sync / push (when online)
+//   cloud provider
+```
+
+The cloud therefore does not **replace** memory: it **replicates** it. This
+gives you: offline-first, lowest latency, data available immediately,
+synchronization when online, multi-device, multi-user, centralized persistence.
+
+We deliberately do **not** provide:
+
+```ts
+// ❌ two mental models
+memory.cloud.save(...)
+```
+
+Instead:
+
+```ts
+memorio.memory.remember('user.language', 'Italian')
+// and a single configuration point:
+memorio.memory.configure({ sync: { provider: myCloudProvider, namespace: '…' } })
+```
+
+## 2. Scopes (isolation, not a security boundary)
+
+| Scope | Lifetime | Syncs by default |
+|---|---|---|
+| `'device'` | this browser/device only | no (sticky) |
+| `'user'` | follows the user across devices | yes (requires provider + namespace) |
+| `'shared'` | shared across users / tenant | yes (requires provider + namespace) |
+
+> As with `memorio.createContext`, **scoping is a naming convention, not a
+> security boundary.** Enforce real isolation server-side.
+
+## 3. SQLite as the local durable store
+
+SQLite (`sql.js`) is **in-memory by default** (volatie per page load). It becomes
+the durable journal/value store when you opt in:
+
+- `sqlite.config({ persistence: true })` / `sqlite.db.create('app', { persistence: true })`
+  snapshot the database to `store` (localStorage) and restore it on reopen.
+- Writes are snapshotted via sql.js `updateHook` (debounced).
+- `sqlite.db.persist(name)` forces an immediate save; `sqlite.db.close(name)`
+  flushes + closes; `sqlite.db.download(name, file?)` triggers a browser
+  `.sqlite` download (dev convenience).
+
+See `docs/markdown/SQLITE.md` for the full SQLite reference.
+
+## 4. The local operation journal
+
+The **sync journal** is the durable op log that drives cloud reconciliation.
+It is persisted on `store` (localStorage) — **not** on an in-memory sql.js db,
+because pending operations must survive a refresh for offline-first to work.
+
+| Method | Returns | Notes |
+|---|---|---|
+| `memory.journal.append(entry, operation)` | `Promise<MemoryEntry>` | records `remember\|update\|forget\|expire\|confirm\|supersede` with `sync:'pending'` |
+| `memory.journal.pending()` | `Promise<MemoryEntry[]>` | rows where `sync != 'synced'`, for the current namespace |
+| `memory.journal.markSynced(ids)` | `Promise<number>` | advances rows to `synced` (namespace-scoped) |
+| `memory.journal.get(id)` | `Promise<MemoryEntry \| null>` | single entry, namespace-scoped |
+| `memory.journal.clear()` | `Promise<void>` | wipes the current namespace's journal |
+| `memory.journal.replay()` | `Promise<SyncAck>` | pushes `pending()` to the provider, marks synced, optional `pull` |
+| `memory.journal.status()` | `Promise<'store'>` | the substrate in use |
+
+We sync **operations of memory**, never a raw database dump:
+
+```
+user A        device A
+remember X ─────► local ─────► sync ─────► cloud
+forget Z ──────► local ─────► sync ─────► cloud
+```
+
+## 5. Conflict resolution
+
+The cloud must not simply say "last write wins." Memorio tags every entry with:
+
+- `confidence` (0–1, user/system trust in the value)
+- `lastConfirmedAt` / `updatedAt` (epoch ms)
+- `version` (monotonic per-key counter)
+- `source` / `scope`
+
+Remote conflicts are surfaced as `sync:'conflict'` rows via
+`journal.pending()`; the provider's `resolve(op)` hint decides locally. Example:
+
+```
+Laptop:  language=Italian, confidence=0.92
+Phone:   language=English, confidence=0.61
+→ higher-confidence entry wins locally; the provider decides for shared scope.
+```
+
+## 6. Configuring a backend
+
+Sync is **opt-in**. You supply an application-owned `provider` that knows how to
+talk to your backend (REST, WebSocket, Supabase, a custom agent server, …).
+
+```ts
+memorio.memory.configure({
+  namespace: 'user:123:device:abc',   // tenant/user/device — partitions the journal
+  provider: {
+    push(ops) { return fetch('/api/sync', { method: 'POST', body: JSON.stringify(ops), headers: authHeaders }) }
+    pull(since) { return fetch(`/api/sync?since=${since}`).then(r => r.json()) }
+    resolve(op) { return op.confidence >= 0.8 ? 'local' : 'remote' }
+  },
+  auto: true                           // auto-replay on focus/online (default true)
+})
+```
+
+```ts
+interface SyncProvider {
+  push(ops: MemoryEntry[]): Promise<{ synced: string[]; conflicts?: string[]; error?: string }>
+  pull?(since?: number): Promise<MemoryEntry[]>
+  resolve?(op: MemoryEntry): Promise<'local' | 'remote' | 'merge'>
+}
+```
+
+`memorio.memory.ready` resolves once the local journal substrate is chosen.
+
+## 7. Security (NIST / OWASP / NSA posture)
+
+- **Memorio never handles credentials.** No passwords, tokens, or API keys are
+  read from or stored by memorio. Authentication/authorization live in your
+  `provider`/backend (OWASP A01: Broken Access Control).
+- **Namespace isolation.** The journal is keyed by `namespace:id` at the storage
+  layer; there is **no API** to enumerate or open another namespace's journal. A
+  client holding a forged/fake namespace simply sees its own (empty) journal.
+- **No dynamic code.** Journal entries are strictly JSON-round-tripped,
+  size-capped (10 MB/entry), and never `eval`'d. The sql.js loader never
+  `import()`s a bare specifier that could be hijacked at build time.
+- **Trust boundary:** memorio owns the local durable copy + operation log; the
+  provider/backend owns remote-side auth and conflict resolution. Memorio
+  surfaces `conflict`/`error` rows; it does not fabricate a winner.
+- **Data-at-rest (NSA/CISA).** memorio's `store`/`idb`/`sqlite` snapshots are
+  **not encrypted**. If you persist user data server-side or ship it through your
+  backend, encrypt it server-side with keys you manage — memorio treats the local
+  store as untrusted-from-the-browser and does not attest its own integrity.
+
+## 8. Where data lives
+
+| Substrate | API | Volatile? | Persistent? |
+|---|---|---|---|
+| in-memory `Proxy` | `state` | yes (per tab) | no |
+| `localStorage` / Map | `store` | no | yes (browser) |
+| `sessionStorage` / Map | `session` | no | per-tab (browser) |
+| IndexedDB | `idb`, `memory` durable | no | yes |
+| sql.js (WASM heap) | `sqlite` | **yes** | only with `persistence: true` (snapshot → `store`) |
+| sync journal | `memory.journal` | no | yes (`store`) |

package/markdown/TYPED.md

@@ -0,0 +1,158 @@
+# Typed Stores - Memorio
+
+> ✅ **Universal**: Works in Browser, Node.js, Deno, and Edge Workers
+
+`memorio.typed<T>()` returns the global `state` proxy cast to a TypeScript type `T`, giving you **compile-time** type safety on every access and mutation.
+
+It's a **zero-runtime-cost** wrapper: the returned object is the *exact same* Proxy as `globalThis.state`, just with TypeScript types applied via a generic.
+
+---
+
+## Quick Start
+
+```typescript
+import 'memorio'
+
+interface AppState {
+  user: { name: string; age: number; email: string }
+  theme: 'light' | 'dark'
+  items: string[]
+}
+
+const app = memorio.typed<AppState>()
+
+// Type-checked at compile time:
+app.user = { name: 'Sara', age: 30, email: 'sara@test.com' }
+app.theme = 'dark'
+
+// TypeScript errors:
+// app.user = { name: 42 }            // age missing, name wrong type
+// app.theme = 'purple'               // not a valid literal
+```
+
+---
+
+## Why use typed stores?
+
+| Without typed | With `memorio.typed<T>()` |
+|---|---|
+| `state.user = { name: 42 }` — runs silently, bug at runtime | `app.user = { name: 42 }` — TypeScript error at compile time |
+| No autocomplete on `state.user.email` | Full IntelliSense: properties, types, method suggestions |
+| Rename `user` to `profile` — no compiler warning anywhere | Every `app.user` access flagged as an error |
+| AI-generated code lacks guardrails | AI gets autocomplete and type feedback inline |
+
+---
+
+## Combine with Schema Validation
+
+Typed stores catch type errors at compile time; schema validation catches invalid values at runtime. Together they form a **defense-in-depth** strategy:
+
+```typescript
+import 'memorio'
+
+interface ProfileState {
+  profile: { bio: string; avatar?: string }
+}
+
+const app = memorio.typed<ProfileState>()
+
+memorio.registerSchema('profile', {
+  type: 'object',
+  required: ['bio'],
+  properties: {
+    bio: { type: 'string', min: 1 },
+    avatar: { type: 'string' }
+  }
+})
+
+app.profile = { bio: 'Developer', avatar: 'pic.png' } // ✅ type + schema pass
+app.profile = { avatar: 'pic.png' }                  // ❌ TypeScript: bio missing
+                                                     // ❌ Runtime: bio required
+```
+
+See [Schema Validation](SCHEMA.md) for runtime validation details.
+
+---
+
+## Named import variant
+
+`typed` is also available as a named export if you prefer explicit dependencies:
+
+```typescript
+import { typed } from 'memorio'
+
+const app = typed<AppState>()
+```
+
+The `memorio` namespace object is the same — `import 'memorio'` is the recommended entry, named exports are an alternative.
+
+---
+
+## Full API
+
+| Method | Parameters | Returns | Description |
+|--------|-----------|---------|-------------|
+| `memorio.typed<T>()` | Generic type `T` | `T` | Returns the global `state` proxy cast to `T` |
+
+The returned object shares the same identity as `globalThis.state`:
+
+```typescript
+const app = memorio.typed<AppState>()
+console.debug(app === state) // true — same Proxy instance
+```
+
+---
+
+## React + typed stores
+
+Pair with the `useObserver` hook for type-safe, reactive React components:
+
+```tsx
+import 'memorio'
+import { useReducer } from 'react'
+
+interface AppState {
+  user: { name: string; age: number }
+  theme: 'light' | 'dark'
+}
+
+const app = memorio.typed<AppState>()
+
+function UserProfile() {
+  const [, forceUpdate] = useReducer(x => x + 1, 0)
+
+  useObserver(forceUpdate, [state.user.name])
+
+  return (
+    <div>
+      <h1>{app.user.name}</h1>
+      <span>Theme: {app.theme}</span>
+    </div>
+  )
+}
+```
+
+---
+
+## Best Practices
+
+1. **Define your AppState at the root** of your app and import it everywhere:
+
+   ```typescript
+   // types/app-state.ts
+   export interface AppState {
+     user: { name: string; email: string }
+     theme: 'light' | 'dark'
+   }
+   ```
+
+   ```typescript
+   // anywhere in your app
+   import 'memorio'
+   import type { AppState } from '../types/app-state'
+   const app = memorio.typed<AppState>()
+   ```
+
+2. **Layer schema validation on top** for runtime safety, especially for data coming from APIs or user input.
+
+3. **Use alongside `memorio.help()`** to list available globals during development.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "memorio",
   "codeName": "memorio",
-  "version": "4.7.1",
+  "version": "4.8.0",
   "description": "Memorio, State + Observer, Store and iDB for an easy life - Cross-platform compatible",
   "main": "./index.cjs",
   "browser": "./index.js",
@@ -34,8 +34,9 @@
     "reactive",
     "universal",
     "cross-platform",
-    "node",
-    "deno",
+    "sqlite",
+    "sql.js",
+    "wasm",
     "browser",
     "frontend"
   ],
@@ -52,15 +53,15 @@
     "markdown/**/*",
     "types/**/*",
     "COPYRIGHT.md",
-    "index.d.ts",
-    "index.cjs",
-    "index.js",
-    "LICENSE.md",
-    "llms.txt",
     "README.md",
     "FUNDING.yml",
     "SECURITY.md",
-    "SUMMARY.md"
+    "SUMMARY.md",
+    "LICENSE.md",
+    "index.d.ts",
+    "index.cjs",
+    "index.js",
+    "llms.txt"
   ],
   "publishConfig": {
     "access": "public"
@@ -77,6 +78,11 @@
   "overrides": {
     "esbuild": "^0.25.0"
   },
+  "peerDependenciesMeta": {
+    "sql.js": {
+      "optional": true
+    }
+  },
   "exports": {
     ".": {
       "import": "./index.js",

package/types/exports.d.ts

@@ -8,12 +8,16 @@
  * @see index.ts (runtime re-export)
  */
 
+/// <reference path="./schema.d.ts" />
+/// <reference path="./history.d.ts" />
+/// <reference path="./inspect.d.ts" />
 /// <reference path="./memorio.d.ts" />
 /// <reference path="./state.d.ts" />
 /// <reference path="./store.d.ts" />
 /// <reference path="./session.d.ts" />
 /// <reference path="./cache.d.ts" />
 /// <reference path="./idb.d.ts" />
+/// <reference path="./sqlite.d.ts" />
 /// <reference path="./observer.d.ts" />
 /// <reference path="./useObserver.d.ts" />
 
@@ -23,6 +27,7 @@ export const store: _store
 export const session: _session
 export const cache: _cache
 export const idb: _idb
+export const sqlite: _sqlite
 export const observer: _observer
 export const useObserver: _useObserver
 export const dispatch: _dispatch
@@ -40,6 +45,28 @@ export const isolate: _memorio['isolate']
 export const message: (...args: unknown[]) => void
 export const help: () => void
 
+export const registerSchema: (path: string, schema: any) => void
+export const validate: (path: string, value: any) => { valid: boolean; errors?: string[] }
+export const unregisterSchema: (path: string) => boolean
+export const listSchemas: () => string[]
+export const typed: <T extends Record<string, any>>() => T
+export const snapshot: () => Record<string, any>
+export const diff: (snap: Record<string, any>) => Array<{ path: string; oldValue: any; newValue: any }>
+export const undo: () => any
+export const redo: () => any
+export const canUndo: () => boolean
+export const canRedo: () => boolean
+export const rollback: (snap: Record<string, any>) => void
+export const trace: () => any[]
+export const enableHistory: (enabled?: boolean) => void
+export const clearHistory: () => void
+export const clearRedo: () => void
+export const stateKeys: () => string[]
+export const pathExists: (path: string) => boolean
+export const stateType: (path: string) => string
+export const stateGet: (path: string) => any
+export const stateSchema: () => Array<{ path: string; type: string; defined: boolean }>
+
 export const propertyName: (container: any, object: any) => string | null
 export const internal: {
   debug: boolean

package/types/history.d.ts

@@ -0,0 +1,27 @@
+/// MEMORIO HISTORY TYPES
+/// Ambient declarations for the snapshot / undo / redo / trace API.
+
+///
+// A single recorded state mutation.
+///
+interface _mutationRecord {
+  /** Dotted state path (e.g. 'user.name'). */
+  path: string
+  /** 'set' or 'delete'. */
+  action: 'set' | 'delete'
+  /** The new value written (for 'set'), undefined for 'delete'. */
+  newValue: any
+  /** The previous value before the mutation. */
+  previousValue: any
+  /** Epoch timestamp (ms) when the mutation occurred. */
+  timestamp: number
+}
+
+///
+// Result of diffing a snapshot against current state.
+///
+interface _diffEntry {
+  path: string
+  oldValue: any
+  newValue: any
+}

package/types/inspect.d.ts

@@ -0,0 +1,14 @@
+/// MEMORIO INSPECT TYPES
+/// Ambient declarations for the state introspection API.
+
+///
+// Schema report entry describing a single state path.
+///
+interface _stateSchemaEntry {
+  /** Dotted path relative to `state`. */
+  path: string
+  /** Runtime type: 'string', 'number', 'boolean', 'object', 'array', 'undefined'. */
+  type: string
+  /** Whether the path resolves to a defined value. */
+  defined: boolean
+}

package/types/memorio.d.ts

@@ -1,3 +1,18 @@
+import type {
+  MemoryEntry,
+  MemorySync,
+  MemoryOperation,
+  SyncProvider,
+  SyncConfig,
+  SyncAck,
+  SyncDirection,
+  RememberOptions,
+  RecallOptions,
+  ContextOptions,
+  ContextEntry,
+  MemoryStats
+} from './memory'
+
 /**
  * Environment capabilities
  */
@@ -60,10 +75,70 @@ interface _memorio {
     session: any
     cache: any
   }
-  help?: () => void
+   help?: () => void
+   // Schema validation
+  registerSchema?: (path: string, schema: any) => void
+  validate?: (path: string, value: any) => { valid: boolean; errors?: string[] }
+  unregisterSchema?: (path: string) => boolean
+  listSchemas?: () => string[]
+  // Typed store
+  typed?: <T extends Record<string, any>>() => T
+  // History / snapshot / undo / redo / trace
+  snapshot?: () => Record<string, any>
+  diff?: (snap: Record<string, any>) => Array<{ path: string; oldValue: any; newValue: any }>
+  undo?: () => _mutationRecord | undefined
+  redo?: () => _mutationRecord | undefined
+  canUndo?: () => boolean
+  canRedo?: () => boolean
+  rollback?: (snap: Record<string, any>) => void
+  trace?: () => _mutationRecord[]
+  enableHistory?: (enabled?: boolean) => void
+  clearHistory?: () => void
+  clearRedo?: () => void
+  // Introspection
+  stateKeys?: () => string[]
+  pathExists?: (path: string) => boolean
+  stateType?: (path: string) => string
+  stateGet?: (path: string) => any
+  stateSchema?: () => Array<{ path: string; type: string; defined: boolean }>
+  memory?: MemoryAPI
+}
+
+interface MemoryAPI {
+  remember<T>(key: string, value: T, opts?: RememberOptions<T>): Promise<void>
+  recall<T>(query: string, opts?: RecallOptions): Promise<T | null>
+  update(key: string, value: any, opts?: Partial<RememberOptions>): Promise<void>
+  forget(key: string): Promise<void>
+  context(opts?: ContextOptions): Promise<ContextEntry[]>
+  stats(): Promise<MemoryStats>
+  forgetExpired(): Promise<number>
+  clear(): Promise<void>
+  /**
+   * Configure the optional cloud-sync layer. Supplying a `provider` (an
+   * application-owned object that knows how to talk to your backend) enables
+   * the local operation journal. The `namespace` (tenant/user/device)
+   * partitions the journal so contexts/tenants cannot read each other's
+   * operations. Memorio never handles credentials — auth lives in the
+   * provider/backend.
+   */
+  configure(opts: SyncConfig): MemoryAPI
+  /** Local operation journal. Writes are namespaced and durable (SQLite when
+   * available, else localStorage). Use `replay()` to push `pending()` entries
+   * to the configured provider. */
+  journal: MemoryJournal
+}
+
+interface MemoryJournal {
+  append(entry: MemoryEntry, operation: MemoryOperation): Promise<MemoryEntry>
+  pending(): Promise<MemoryEntry[]>
+  markSynced(ids: string[]): Promise<number>
+  get(id: string): Promise<MemoryEntry | null>
+  clear(): Promise<void>
+  replay(): Promise<SyncAck>
+  status(): Promise<'store'>
 }
 
-type memorio = _memorio
+type memorio = _memorio
 declare var memorio: _memorio
 
 interface GlobalMemorio {

package/types/memory.d.ts

@@ -0,0 +1,127 @@
+export type MemoryScope = 'hot' | 'session' | 'local' | 'durable'
+
+export type MemoryType =
+  | 'fact'
+  | 'preference'
+  | 'decision'
+  | 'task'
+  | 'context'
+
+export type MemoryStatus = 'active' | 'obsolete' | 'superseded'
+
+/**
+ * Logical operations recorded in the local sync journal.
+ * The cloud side only ever sees operations — never a raw dump of a substrate.
+ */
+export type MemoryOperation =
+  | 'remember'
+  | 'update'
+  | 'forget'
+  | 'expire'
+  | 'confirm'
+  | 'supersede'
+
+/**
+ * Synchronization state of a journal entry against a remote/cloud backend.
+ */
+export type MemorySync = 'pending' | 'synced' | 'conflict' | 'error'
+
+export type SyncDirection = 'up' | 'down' | 'both'
+
+/**
+ * Pluggable cloud/sync transport. Memorio never ships a credential flow:
+ * the application supplies a `provider` that knows how to talk to its backend
+ * (REST, WebSocket, Supabase, a custom agent server, ...). Memorio owns the
+ * local journal, the provider only moves operations.
+ */
+export interface SyncProvider {
+  /** Pushes pending local operations; returns ids that were accepted */
+  push(ops: MemoryEntry[]): Promise<{ synced: string[]; conflicts?: string[]; error?: string }>
+  /** Optional pull of remote operations newer than `since` (epoch ms) */
+  pull?(since?: number): Promise<MemoryEntry[]>
+  /** Optional conflict resolution hint: 'local' | 'remote' | 'merge' */
+  resolve?(op: MemoryEntry): Promise<'local' | 'remote' | 'merge'>
+}
+
+export interface SyncConfig {
+  /** Sync provider implementation (application supplied) */
+  provider?: SyncProvider
+  /** Which direction to sync; 'both' is the default */
+  direction?: SyncDirection
+  /** Auto-sync on every local write? defaults to true */
+  auto?: boolean
+}
+
+export interface SyncAck {
+  synced: string[]
+  conflicts?: string[]
+  error?: string
+}
+
+export interface MemoryEntry<T = any> {
+  id: string
+  key: string
+  value: T
+  type: MemoryType
+  confidence: number
+  scope: MemoryScope
+  ttl?: number | null
+  tags: string[]
+  source?: string
+  status: MemoryStatus
+  createdAt: number
+  lastConfirmedAt: number
+  supersededId?: string | null
+  /** Monotonic per-key write counter, used for last-writer / conflict resolution */
+  version?: number
+  /** Epoch ms of the last mutation that touched this entry */
+  updatedAt?: number
+  /** Last logical operation that produced this entry */
+  operation?: MemoryOperation
+  /** Local-cloud sync state of the entry (undefined => not tracked for sync) */
+  sync?: MemorySync
+}
+
+export interface RememberOptions<T = any> {
+  id?: string
+  type?: MemoryType
+  confidence?: number
+  scope?: MemoryScope
+  ttl?: number | null
+  tags?: string | string[]
+  source?: string
+}
+
+export interface RecallOptions {
+  type?: MemoryType | MemoryType[]
+  tags?: string | string[]
+  minConfidence?: number
+  includeObsolete?: boolean
+}
+
+export interface ContextOptions {
+  tags?: string | string[]
+  types?: MemoryType | MemoryType[]
+  minConfidence?: number
+  maxEntries?: number
+  scopes?: MemoryScope[]
+}
+
+export interface ContextEntry {
+  key: string
+  value: any
+  type: MemoryType
+  confidence: number
+  scope: MemoryScope
+  tags: string[]
+  age: number
+  accessCount: number
+  lastAccessedAt: number
+}
+
+export interface MemoryStats {
+  total: number
+  byScope: Record<MemoryScope, number>
+  byType: Partial<Record<MemoryType, number>>
+  expired: number
+}