memorio 4.9.35 → 5.0.0

package/markdown/IMPORT.md

@@ -0,0 +1,153 @@
+> **Status:** Published
+> **Date:** 2026-09-12
+> **Deciders:** Memorio 5.x Core Team
+> **Scope**: API Reference
+> **Standard**: Memorio API Specification v5
+>
+---
+# Classic `import` support
+
+Memorio supports two styles: the explicit named-import style (recommended),
+and the global side-effect entrypoint for when global access is explicitly desired.
+Both share the same instances (one source of truth).
+
+```typescript
+// Explicit named imports (recommended for normal usage)
+import { state } from 'memorio'
+state.user = { name: 'Sara' }
+
+// Global entrypoint (opt-in for global access)
+import 'memorio/global'
+state.user = { name: 'Sara' }
+```
+
+`state` in both examples is the exact same Proxy object.
+
+---
+
+## Why two styles?
+
+| Style | When to use |
+|-------|-------------|
+| `import { state } from 'memorio'` | Explicit dependencies, tree-shakeable bundles, TypeScript IntelliSense |
+| `import 'memorio/global'` | When global access is explicitly desired (legacy scripts, shell-style usage) |
+
+---
+
+## 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()   // dev-only introspection
+```
+
+---
+
+## 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 as the global entrypoint. Mutating via a named export mutates the same proxy instance that `import 'memorio/global'` would install on `globalThis`, and vice versa.
+
+```typescript
+import { state } from 'memorio'
+
+state.importedFlag = true
+console.debug(globalThis.state?.importedFlag) // true (when global entrypoint is loaded)
+```
+
+---
+
+## Migration to explicit imports
+
+If you previously used `import 'memorio'` for global access, migrate to either:
+
+```typescript
+// Option A: named imports (recommended)
+import { state, store } from 'memorio'
+
+// Option B: explicit global entrypoint (opt-in)
+import 'memorio/global'
+// state, store, etc. are now on globalThis
+```

package/markdown/INSPECT.md

@@ -0,0 +1,123 @@
+> **Status:** Published
+> **Date:** 2026-09-12
+> **Deciders:** Memorio 5.x Core Team
+> **Scope**: API Reference
+> **Standard**: Memorio API Specification v5
+>
+---
+# 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 { state, memorio } from '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

@@ -0,0 +1,154 @@
+> **Status:** Published
+> **Date:** 2026-09-12
+> **Deciders:** Memorio 5.x Core Team
+> **Scope**: API Reference
+> **Standard**: Memorio API Specification v5
+>
+---
+# 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

@@ -0,0 +1,96 @@
+> **Status:** Published
+> **Date:** 2026-09-12
+> **Deciders:** Memorio 5.x Core Team
+> **Scope**: API Reference
+> **Standard**: Memorio API Specification v5
+>
+---
+# 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.
+
+## 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

@@ -0,0 +1,162 @@
+> **Status:** Published
+> **Date:** 2026-09-12
+> **Deciders:** Memorio 5.x Core Team
+> **Scope**: API Reference
+> **Standard**: Memorio API Specification v5
+>
+---
+# 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 |