memorio 4.7.3 → 4.9.5

package/markdown/IMPORT.md

@@ -1,139 +0,0 @@
-# Classic `import` support
-
-Memorio supports two equivalent styles: the original global side-effect import,
-and the new named exports. Both share the same instances (one source of truth).
-
-```typescript
-// Global style (original)
-import 'memorio'
-state.user = { name: 'Sara' }
-
-// Classic import style (new)
-import { state } from 'memorio'
-state.user = { name: 'Sara' }
-```
-
-`state` in both examples is the exact same Proxy object.
-
----
-
-## Why two styles?
-
-| Style | When to use |
-|-------|-------------|
-| `import 'memorio'` | Zero-config, global access everywhere, legacy scripts |
-| `import { state } from 'memorio'` | Explicit dependencies, tree-shakeable bundles, TypeScript IntelliSense |
-
----
-
-## ESM named imports
-
-All modules are available as named exports:
-
-```typescript
-import {
-  state,
-  store,
-  session,
-  cache,
-  idb,
-  observer,
-  useObserver,
-  dispatch,
-  message,
-  devtools,
-  logger
-} from 'memorio'
-```
-
-Platform helpers:
-
-```typescript
-import {
-  isBrowser,
-  isNode,
-  isDeno,
-  isEdge,
-  getCapabilities,
-  createContext,
-  listContexts,
-  deleteContext
-} from 'memorio'
-```
-
-Internal utilities (for tests/debug):
-
-```typescript
-import internal, { propertyName } from 'memorio'
-import { setContext, getContext } from 'memorio'
-```
-
-Default export (the public `memorio` namespace):
-
-```typescript
-import memorio from 'memorio'
-memorio.help()
-```
-
----
-
-## CJS usage
-
-```javascript
-const { state, store, memorio } = require('memorio')
-```
-
----
-
-## React / useObserver
-
-`useObserver` works the same way via named import:
-
-```tsx
-import { useObserver, state } from 'memorio'
-
-function Counter() {
-  const [, forceUpdate] = useReducer(x => x + 1, 0)
-
-  useObserver(forceUpdate, [state.counter])
-
-  return <div>Count: {state.counter}</div>
-}
-```
-
----
-
-## Context isolation
-
-```typescript
-import { createContext, listContexts, deleteContext, isolate } from 'memorio'
-
-const ctx = createContext('tenant-123')
-ctx.state.user = { name: 'Isolated' }
-ctx.store.set('settings', { theme: 'dark' })
-
-listContexts() // ['tenant-123']
-deleteContext('tenant-123')
-```
-
----
-
-## Same-instance guarantee
-
-Named exports point to the same instances published on `globalThis` by
-`core/global` at bootstrap. Mutating via named export mutates the global,
-and vice versa.
-
-```typescript
-import { state } from 'memorio'
-
-state.importedFlag = true
-console.debug(globalThis.state.importedFlag) // true
-```
-
----
-
-## Migration from global-only
-
-No code changes required. Existing `import 'memorio'` + `state.foo = 1`
-continues to work unchanged. Named exports are additive.

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.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 |