memorio 4.8.0 → 4.9.5

package/markdown/INSPECT.md

@@ -1,116 +0,0 @@
-# Introspection & Inspection - Memorio
-
-> ✅ **Universal**: Works in Browser, Node.js, Deno, and Edge Workers
-
-Introspection utilities let you programmatically discover, verify, and read the shape of the global `state` proxy. Essential for AI agents that need to check whether a path exists before writing, or enumerate available keys before reading.
-
----
-
-## stateKeys()
-
-Returns all top-level keys currently on the `state` proxy. Excludes internal properties.
-
-```javascript
-import 'memorio'
-
-state.user = { name: 'Sara' }
-state.counter = 42
-
-memorio.stateKeys()   // ['user', 'counter']
-```
-
----
-
-## pathExists(path)
-
-Checks whether a dotted path exists in state. Returns `true` if the path resolves to a non-undefined value.
-
-```javascript
-state.user = { name: 'Sara', profile: { age: 30 } }
-
-memorio.pathExists('user')           // true
-memorio.pathExists('user.name')      // true
-memorio.pathExists('user.profile')   // true
-memorio.pathExists('user.profile.age') // true
-memorio.pathExists('user.age')       // false
-memorio.pathExists('nonexistent')    // false
-```
-
-This is critical for AI agents: always check `pathExists` before writing to a nested path to avoid creating unintended intermediate objects.
-
----
-
-## stateType(path)
-
-Returns the runtime type of the value at a given state path.
-
-```javascript
-state.count = 42
-state.name = 'Sara'
-state.items = [1, 2, 3]
-
-memorio.stateType('count')    // 'number'
-memorio.stateType('name')     // 'string'
-memorio.stateType('items')    // 'array'
-memorio.stateType('missing')  // 'undefined'
-```
-
----
-
-## stateGet(path)
-
-Returns the value at a dotted path, deep-cloned to prevent accidental mutation of state.
-
-```javascript
-state.user = { name: 'Sara', tags: ['admin'] }
-
-const user = memorio.stateGet('user')   // { name: 'Sara', tags: ['admin'] }
-user.name = 'Luigi'                      // mutates the clone, not state
-state.user.name                         // still 'Sara'
-```
-
----
-
-## stateSchema()
-
-Generates a full schema report of the current state tree — every path with its type and whether it's defined.
-
-```javascript
-state.user = { name: 'Sara', age: 30 }
-state.theme = 'dark'
-
-memorio.stateSchema()
-// [
-//   { path: 'user',      type: 'object', defined: true },
-//   { path: 'user.name', type: 'string', defined: true },
-//   { path: 'user.age',  type: 'number', defined: true },
-//   { path: 'theme',     type: 'string', defined: true }
-// ]
-```
-
-This is the **most useful for AI agents** — it gives a complete picture of what's in state and what types the values are, in a single call. Perfect for:
-- Discovering available state before generating code
-- Validating that expected paths exist
-- Understanding the shape of nested objects
-
----
-
-## Full API
-
-| Method | Parameters | Returns | Description |
-|--------|-----------|---------|-------------|
-| `memorio.stateKeys()` | none | `string[]` | Top-level state keys |
-| `memorio.pathExists(path)` | `string` | `boolean` | Whether a path resolves to a value |
-| `memorio.stateType(path)` | `string` | `string` | Runtime type at path |
-| `memorio.stateGet(path)` | `string` | `any` | Deep-cloned value at path |
-| `memorio.stateSchema()` | none | `SchemaEntry[]` | Full state tree report |
-
----
-
-## How It Works
-
-All introspection functions read from the global `state` proxy via `deepRaw()` — the same function used internally by the state proxy to unwrap itself before storing. This ensures consistent, non-proxied values are returned.
-
-- `pathExists` and `stateGet` split the path on `.` and traverse the state tree.
-- `stateSchema` recursively walks the state object, collecting every path and its type.
-- All returned values from `stateGet` and `snapshot` are deep clones (via JSON round-trip) to prevent accidental mutation.

package/markdown/LOGGER.md

@@ -1,147 +0,0 @@
-# Memorio Logger
-
-> 🖥️ **Browser Only**: This feature is only available in browser console
-
-Automatic logging middleware for tracking all state changes in Memorio.
-
-## Overview
-
-The logger automatically tracks all operations (set, delete, clear) across all modules:
-- State
-- Store
-- Session
-- Cache
-
-## Configuration
-
-### configure(options)
-
-Configure the logger.
-
-```javascript
-memorio.logger.configure({
-  enabled: true,           // Enable/disable logging
-  logToConsole: true,     // Log to browser console
-  customHandler: function(entry) { ... }, // Custom handler
-  modules: ['state', 'store', 'session', 'cache'], // Modules to log
-  maxEntries: 1000        // Maximum log history size
-})
-```
-
-### enable()
-
-Enable logging.
-
-```javascript
-memorio.logger.enable()
-```
-
-### disable()
-
-Disable logging.
-
-```javascript
-memorio.logger.disable()
-```
-
-## Methods
-
-### getHistory()
-
-Get all log entries.
-
-```javascript
-const history = memorio.logger.getHistory()
-// Returns array of LogEntry objects
-```
-
-### getStats()
-
-Get statistics about logged operations.
-
-```javascript
-const stats = memorio.logger.getStats()
-// Returns: { total, state, store, session, cache, set, get, delete, clear }
-```
-
-### clearHistory()
-
-Clear log history.
-
-```javascript
-memorio.logger.clearHistory()
-```
-
-### exportLogs()
-
-Export logs as JSON string.
-
-```javascript
-const json = memorio.logger.exportLogs()
-```
-
-## Log Entry Structure
-
-```javascript
-{
-  timestamp: "2026-02-18T12:00:00.000Z",
-  module: "state",
-  action: "set",
-  path: "user.name",
-  value: "John",
-  previousValue: "Jane"
-}
-```
-
-## Examples
-
-### Basic usage
-
-```javascript
-// Logging is enabled by default
-state.user = { name: 'John' }
-// Console: [Memorio:STATE] set user → value: { name: 'John' }
-```
-
-### Get statistics
-
-```javascript
-const stats = memorio.logger.getStats()
-console.debug(stats)
-// { total: 15, state: 5, store: 3, session: 2, cache: 5, set: 10, get: 0, delete: 3, clear: 2 }
-```
-
-### Disable specific modules
-
-```javascript
-memorio.logger.configure({
-  modules: ['state'] // Only log state changes
-})
-```
-
-### Custom handler
-
-```javascript
-memorio.logger.configure({
-  customHandler: (entry) => {
-    // Send to analytics
-    analytics.track('memorio_change', entry)
-  }
-})
-```
-
-### Export and analyze
-
-```javascript
-// Get all logs
-const logs = memorio.logger.getHistory()
-
-// Filter by module
-const stateLogs = logs.filter(l => l.module === 'state')
-
-// Filter by action
-const setOperations = logs.filter(l => l.action === 'set')
-
-// Export for debugging
-console.debug(memorio.logger.exportLogs())
-```

package/markdown/MEMORY-ATTACHMENT.md

@@ -1,95 +0,0 @@
-# Node Attachment System
-
-`memorio.memory` extends with a **Node Attachment System** allowing memory elements to dynamically attach, reference, or connect to other memory elements at runtime.
-
-This is an **extension**, not a replacement, of existing memory semantics.
-
-## Concepts
-
-```text
-Memory
- └── Node
-      ├── identity
-      ├── value
-      ├── metadata
-      └── relationships
-            └── Edge
-                 ├── target
-                 ├── relation
-                 ├── metadata
-                 ├── confidence
-                 └── lifecycle
-```
-
-## API
-
-```ts
-const user = await memory.remember("user", { name: "Alice" })
-const project = await memory.remember("project", { name: "Memorio" })
-
-await user.connect(project, { relation: "works-on", confidence: 0.95 })
-await user.attach(project)  // → connect with relation "attached-to"
-
-const related = await user.related({ direction: "both", relation: "works-on" })
-const tree = await user.traverse({ depth: 3 })
-```
-
-### Methods
-
-| Method | Description |
-|--------|-------------|
-| `node.connect(target, opts?)` | Create a directed relationship |
-| `node.disconnect(target, opts?)` | Remove a relationship |
-| `node.related(opts?)` | Query related nodes |
-| `node.traverse(opts?)` | Bounded graph traversal |
-| `memory.connect(source, target, opts?)` | Low-level connect |
-| `memory.disconnect(source, target, opts?)` | Low-level disconnect |
-
-## Scopes
-
-Relationship visibility respects memory scopes — a query in one scope cannot leak inaccessible nodes from another.
-
-## Persistence
-
-Relationships use **IDs**, never embedded objects:
-
-```json
-{
-  "id": "user",
-  "relationships": [
-    { "target": "project", "relation": "works-on" }
-  ]
-}
-```
-
-## Lifecycle
-
-- **TTL**: independent per node/edge — does not propagate
-- **Confidence**: independent — node and edge have separate confidence values
-- **Deletion**: deleting a node removes its edges (default policy)
-- **Cycles**: supported with visited-set protection during traversal
-- **Dangling references**: `retain` by default (configurable)
-
-## Security
-
-Relationship traversal inherits the same scope/access rules as direct retrieval. A user cannot gain access to Node B merely because Node A connects to it.
-
-## Experimental Substrate Evaluation
-
-Runtime substrate choices (Object Graph, WeakMap, DOM) are under benchmark evaluation. See:
-
-- [Leak Detection Protocol](../experimental/memory-substrates/LEAK-DETECTION.md)
-
-## Serialization
-
-Nodes serialize to IDs only — never recursively embedded graphs.
-
-## Performance
-
-- `O(1)` indexed lookup for direct node retrieval
-- Graph traversal only on explicit request
-- Indexable by `source`, `target`, `relation`
-
-## Backward Compatibility
-
-Existing APIs (`remember`, `get`, `forget`, `search`) continue to work unchanged. A node-enabled memory entry remains usable as a normal memory entry.

package/markdown/MEMORY.md

@@ -1,155 +0,0 @@
-# Memory System
-
-`memorio.memory` provides a semantic memory layer — a key/value store with type safety, TTL, confidence scoring, tagging, and scope-based persistence.
-
-## Core API
-
-### `memorio.memory.remember(key, value, opts?)`
-
-Stores a memory entry.
-
-```ts
-await memorio.memory.remember('user.name', 'Dario', {
-  type: 'preference',
-  confidence: 0.92,
-  scope: 'local',
-  ttl: null,
-  tags: ['user', 'profile'],
-  source: 'conversation'
-})
-```
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `id` | `string` | `key` | Custom entry ID |
-| `type` | `'fact' \| 'preference' \| 'decision' \| 'task' \| 'context'` | `'fact'` | Semantic classification |
-| `confidence` | `number` | `1.0` | Trust score 0.0–1.0 |
-| `scope` | `'hot' \| 'session' \| 'local' \| 'durable'` | auto | Storage backend (see below) |
-| `ttl` | `number \| null` | `null` | Milliseconds before expiry (`null` = never) |
-| `tags` | `string \| string[]` | `[]` | Metadata for filtering |
-| `source` | `string` | `undefined` | Origin of the memory |
-
-### `memorio.memory.recall(query, opts?)`
-
-Retrieves a memory by key.
-
-```ts
-const name = await memorio.memory.recall('user.name')
-const highConfidence = await memorio.memory.recall('project', {
-  minConfidence: 0.8
-})
-```
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `type` | `MemoryType \| MemoryType[]` | `*` | Filter by type |
-| `tags` | `string \| string[]` | `*` | Filter by tags |
-| `minConfidence` | `number` | `0` | Minimum confidence threshold |
-| `includeObsolete` | `boolean` | `false` | Include expired/superseded entries |
-
-### `memorio.memory.update(key, value, opts?)`
-
-Updates an existing memory. Creates a **superseded copy** of the old entry (preserving history).
-
-```ts
-await memorio.memory.update('user.name', 'Alice', { confidence: 0.95 })
-```
-
-### `memorio.memory.forget(key)`
-
-Permanently removes a memory.
-
-```ts
-await memorio.memory.forget('user.temp')
-```
-
-### `memorio.memory.context(opts?)`
-
-Returns ranked, relevant memories. Uses recency × confidence × type/scope boost algorithm.
-
-```ts
-const ctx = await memorio.memory.context({
-  tags: 'project',
-  types: ['decision', 'preference'],
-  minConfidence: 0.7,
-  maxEntries: 10,
-  scopes: ['local', 'durable']
-})
-```
-
-Returns:
-```ts
-Array<{
-  key: string
-  value: any
-  type: MemoryType
-  confidence: number
-  scope: MemoryScope
-  tags: string[]
-  age: number          // milliseconds since createdAt
-  accessCount: number
-  lastAccessedAt: number
-}>
-```
-
-### `memorio.memory.stats()`
-
-Returns usage statistics:
-
-```ts
-{
-  total: number
-  byScope: Record<MemoryScope, number>
-  byType: Partial<Record<MemoryType, number>>
-  expired: number
-}
-```
-
-### `memorio.memory.forgetExpired()`
-
-Cleans all expired entries. Returns count removed.
-
-### `memorio.memory.clear()`
-
-Wipes all memories and the index.
-
-## Memory Entry Model
-
-```ts
-interface MemoryEntry<T = any> {
-  id: string
-  key: string
-  value: T
-  type: 'fact' | 'preference' | 'decision' | 'task' | 'context'
-  confidence: number
-  scope: 'hot' | 'session' | 'local' | 'durable'
-  ttl?: number | null
-  tags: string[]
-  source?: string
-  status: 'active' | 'obsolete' | 'superseded'
-  createdAt: number
-  lastConfirmedAt: number
-  supersededId?: string | null
-}
-```
-
-## Scopes
-
-| Scope | Storage | TTL | Cross-session | Size limit |
-|-------|---------|-----|---------------|------------|
-| `hot` | `state` proxy | ✅ | ❌ | ~5MB (RAM) |
-| `session` | `sessionStorage` | ✅ | Tab only | ~5MB |
-| `local` | `localStorage` | ✅ | ✅ | ~10MB |
-| `durable` | `IndexedDB` | ✅ | ✅ | ~1GB+ |
-
-Default scope is `local` for values ≤100KB, `durable` for larger values.
-
-## Memory Lifecycle
-
-| Event | Behavior |
-|-------|----------|
-| `remember()` on existing key | Old entry → `superseded`, new entry → `active` |
-| Entry with TTL expires | Status → `obsolete` (cleaned by `forgetExpired()`) |
-| `recall()` expired entry | Returns `null` unless `includeObsolete: true` |
-| `update()` | Creates superseded copy + updated active entry |
-| `clear()` | Wipes all memories + index |

package/markdown/OBSERVER.md

@@ -1,200 +0,0 @@
-# Observer - Memorio
-
-Observer lets you react to state changes. When a state key changes, your callback function runs.
-
-## Installation
-
-```bash
-npm install memorio
-```
-
-```javascript
-import 'memorio';
-```
-
----
-
-## Quick Examples
-
-### Example 1: Basic Usage
-
-```javascript
-observer('state.counter', (newValue) => {
-  console.debug('Counter is now:', newValue);
-});
-
-state.counter = 1;
-// Output: "Counter is now: 1"
-
-state.counter = 5;
-// Output: "Counter is now: 5"
-```
-
-### Example 2: Intermediate
-
-```javascript
-// Observer with old value
-observer('state.user', (newValue, oldValue) => {
-  console.debug(`User changed from ${oldValue?.name} to ${newValue?.name}`);
-});
-
-state.user = { name: 'Mario' };
-// Output: "User changed from undefined to Mario"
-
-state.user = { name: 'Luigi' };
-// Output: "User changed from Mario to Luigi"
-```
-
-### Example 3: Advanced
-
-```javascript
-// Multiple callbacks for same path
-observer('state.data', [handler1, handler2]);
-
-// List all observers
-console.debug(observer.list);
-// Output: [{ name: 'state.data', id: '...' }, ...]
-
-// Remove specific observer
-observer.remove('state.data');
-
-// Remove all observers
-observer.removeAll();
-
-// Check if observer exists
-if (observer.has('state.counter')) {
-  console.debug('Observer exists for counter');
-}
-```
-
----
-
-## Direct Values (Vanilla JS)
-
-Observer supports direct state values, not just string paths:
-
-```javascript
-// Direct value - no string needed!
-observer(state.counter, (newValue) => {
-  console.debug('Counter:', newValue);
-});
-
-// Works with objects too
-observer(state.user, (newValue) => {
-  console.debug('User:', newValue?.name);
-});
-
-// Multiple callbacks as array
-observer('state.data', [cb1, cb2, cb3]);
-```
-
----
-
-## API Reference
-
-### observer(path, callback, option)
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `path` | `string \| object` | State path (e.g., `'state.counter'`) or direct state value |
-| `callback` | `function \| array` | Function(s) called on change. Can be a single function or array of functions |
-| `option` | `boolean` | Listen continuously (default: `true`) |
-
-### Callback Parameters
-
-```javascript
-observer('state.key', (newValue, oldValue) => {
-  // newValue: the new value
-  // oldValue: the previous value
-});
-```
-
-### Properties
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `observer.list` | `Array` | Get all active observers |
-
-### Methods
-
-| Method | Parameters | Description |
-|--------|------------|-------------|
-| `observer.remove(name)` | `string` | Remove observer for specific path |
-| `observer.removeAll()` | none | Remove all observers |
-| `observer.has(name)` | `string` | Check if observer exists for path (returns boolean) |
-
----
-
-## React Integration
-
-### With useState
-
-```javascript
-const [count, setCount] = useState(0);
-
-observer('state.counter', () => {
-  setCount(state.counter);
-});
-```
-
-### With useEffect
-
-```javascript
-useEffect(() => {
-  const handleChange = (newVal) => {
-    console.debug('Changed:', newVal);
-  };
-
-  observer('state.data', handleChange);
-
-  // Cleanup
-  return () => observer.remove('state.data');
-}, []);
-```
-
----
-
-## How It Works
-
-Observer subscribes to state changes via the Proxy's set trap. When `state.key = value` is called:
-1. The Proxy intercepts the set
-2. Fires all callbacks registered for that path
-3. Callbacks receive newValue and oldValue
-
----
-
-## Best Practices
-
-1. Clean up observers in React `useEffect` return
-2. Use specific paths: `'state.user.name'` not `'state'`
-3. Remove observers when components unmount
-4. Use `observer.removeAll()` on page navigation
-
----
-
-## Common Patterns
-
-### Form Validation
-
-```javascript
-observer('state.form.email', (email) => {
-  const isValid = email.includes('@');
-  state.form.isValid = isValid;
-});
-```
-
-### Analytics
-
-```javascript
-observer('state.page', (page) => {
-  analytics.track('page_view', { page });
-});
-```
-
-### Auto-save
-
-```javascript
-observer('state.draft', (content) => {
-  store.set('autosave', content);
-});
-```