memorio 5.1.3 → 5.2.0

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "memorio",
   "codeName": "memorio",
-  "version": "5.1.3",
-  "description": "Memorio, State + Observer, Store and iDB for an easy life - Cross-platform compatible",
+  "version": "5.2.0",
+  "description": "The user-owned memory layer for AI agents and apps, with reactive state, persistence, acquired experience, discovery, and context projection.",
   "main": "./index.cjs",
   "browser": {
     "./index.js": "./index.js",
@@ -50,7 +50,10 @@
     "bun",
     "cross-runtime",
     "browser",
-    "frontend"
+    "frontend",
+    "ai-agent",
+    "agent-memory",
+    "acquired-experience"
   ],
   "funding": [
     {
@@ -63,8 +66,7 @@
     "bun": ">=1.4.0"
   },
   "files": [
-    "bin",
-    "vsix",
+    "bin/**/*",
     "markdown/**/*",
     "types/**/*",
     "examples/**/*",
@@ -100,6 +102,13 @@
     "url": "https://dario.passariello.ca/",
     "email": "dariopassariello@gmail.com"
   },
+  "optionalDependencies": {
+    "sql.js": "^7.13.0"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "sql.js": ">=7.0.0"
+  },
   "peerDependenciesMeta": {
     "sql.js": {
       "optional": true

package/types/exports.d.ts

@@ -10,7 +10,9 @@
 
 /// <reference path="./schema.d.ts" />
 /// <reference path="./history.d.ts" />
-/// <reference path="./mutation.d.ts" />
+/// <reference path="./mutation.d.ts" />
+/// <reference path="./logic.d.ts" />
+/// <reference path="./temporal.d.ts" />
 /// <reference path="./inspect.d.ts" />
 /// <reference path="./memorio.d.ts" />
 /// <reference path="./state.d.ts" />
@@ -38,8 +40,47 @@ export const useObserver: _useObserver
 export const encryption: _encryption
 export const computed: _computed
 export const broadcast: _broadcast
-export const security: _security
-export const dispatch: _dispatch
+export const security: _security
+export const memory: MemoryAPI
+export { logic, LogicEngine } from './logic'
+export type MemInspectionStatus = 'valid' | 'invalid' | 'checksum_mismatch' | 'unsupported' | 'corrupt'
+export interface MemInspection {
+  status: MemInspectionStatus
+  representation: 'json-v1' | 'json-v2' | 'package-v1' | 'unknown'
+  message: string
+  packageVersion?: number
+  memoryVersion?: number
+  contentId?: string
+  parts: Array<{ path: string; bytes: number; protected: boolean }>
+  knowledge?: {
+    version: number
+    claims: AcquiredClaim[]
+  }
+  unknownSemantics?: {
+    mapEntries: number
+    vocabularyEntries: number
+    extensionParts: string[]
+  }
+  integrity?: {
+    status: 'valid'
+    algorithm: 'sha256'
+    contentId: string
+  }
+  authenticity?: {
+    status: 'unsigned' | 'valid' | 'invalid' | 'unsupported'
+    trust: 'not_evaluated'
+    signatures: Array<{
+      status: 'valid' | 'invalid' | 'unsupported'
+      algorithm?: string
+      keyId?: string
+      contentId?: string
+      message: string
+    }>
+  }
+}
+export const inspectMem: (input: string | Uint8Array) => Promise<MemInspection>
+export const signMemPackage: (input: Uint8Array, privateKey: CryptoKey, publicKey: CryptoKey) => Promise<Uint8Array>
+export const dispatch: _dispatch
 export const events: Record<string, any>
 
 export const DEV: boolean
@@ -64,6 +105,9 @@ export const fractional: {
   reindex<T extends { key: string }>(items: T[]): T[]
 }
 
+// ── Temporal Memory Runtime ───────────────────────────────────────────
+export const temporal: _temporal
+
 export const isBrowser: () => boolean
 export const isNode: () => boolean
 export const isDeno: () => boolean

package/types/logic.d.ts

@@ -0,0 +1,79 @@
+import type {
+  AcquiredClaim,
+  AcquiredContext,
+  ClaimProvenance,
+  EpistemicType,
+  EvidenceReference,
+  JsonPrimitive,
+  JsonValue
+} from './memory'
+
+export type LogicEpistemicType = EpistemicType
+
+export interface LogicExperienceInput {
+  situation: JsonValue
+  action: JsonValue
+  outcome: JsonValue
+  evidence: EvidenceReference[]
+}
+
+export interface LogicExperienceOptions extends LogicExperienceInput {
+  id: string
+  applicability: Record<string, JsonPrimitive>
+  epistemicType?: LogicEpistemicType
+  provenance?: ClaimProvenance
+  acquiredAt?: string
+  refines?: string | string[]
+  supersedes?: string | string[]
+  retracts?: string | string[]
+  reason?: string
+}
+
+export interface LogicQuery {
+  context: Record<string, JsonPrimitive>
+}
+
+export interface LogicMeasurement {
+  total: number
+  selected: number
+  selectedIds: string[]
+  knowledgeVersion: number
+  temporalMutations: number
+}
+
+export interface LogicRule {
+  id: string
+  condition: JsonValue
+  recommendation: JsonValue
+  evidence: EvidenceReference[]
+  confidence: number
+}
+
+export interface LogicStats {
+  experiences: number
+  version: number
+}
+
+export interface LogicEngineAPI {
+  experience(opts: LogicExperienceOptions): Promise<void>
+  precedents(query: LogicQuery): Promise<AcquiredClaim[]>
+  context(query: LogicQuery): Promise<AcquiredContext>
+  measure(query: LogicQuery): Promise<LogicMeasurement>
+  learn(query: LogicQuery): Promise<LogicRule[]>
+  clear(): Promise<void>
+  stats(): Promise<LogicStats>
+}
+
+export class LogicEngine implements LogicEngineAPI {
+  experience(opts: LogicExperienceOptions): Promise<void>
+  precedents(query: LogicQuery): Promise<AcquiredClaim[]>
+  context(query: LogicQuery): Promise<AcquiredContext>
+  measure(query: LogicQuery): Promise<LogicMeasurement>
+  learn(query: LogicQuery): Promise<LogicRule[]>
+  clear(): Promise<void>
+  stats(): Promise<LogicStats>
+  configure(opts: { disabled?: boolean }): void
+}
+
+export const logic: LogicEngine
+export default logic

package/types/memorio.d.ts

@@ -6,13 +6,21 @@ import type {
   SyncConfig,
   SyncAck,
   SyncDirection,
-  RememberOptions,
-  RecallOptions,
-  ContextOptions,
-  ContextEntry,
-  MemoryStats,
-  PatchOperation
-} from './memory'
+  RememberOptions,
+  RecallOptions,
+  ContextOptions,
+  AcquiredContextOptions,
+  ContextEntry,
+  AcquireOptions,
+  AcquiredContext,
+  DiscoveryOptions,
+  DiscoveryResult,
+  ContextProjection,
+  ProjectionOptions,
+  MemoryStats,
+  PatchOperation
+} from './memory'
+import type { LogicEngine } from './logic'
 
 /**
  * Environment capabilities
@@ -111,8 +119,10 @@ interface _memorio {
   stateType?: (path: string) => string
   stateGet?: (path: string) => any
   stateSchema?: () => Array<{ path: string; type: string; defined: boolean }>
-  memory?: MemoryAPI
-  encryption?: _encryption
+   memory?: MemoryAPI
+   temporal?: _temporal
+   logic?: LogicEngine
+   encryption?: _encryption
   computed?: _computed
   broadcast?: _broadcast
   security?: _security
@@ -123,13 +133,19 @@ interface _memorio {
   [key: string]: any
 }
 
-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>
-  patch(key: string, patches: PatchOperation[]): Promise<void>
-  context(opts?: ContextOptions): Promise<ContextEntry[]>
+interface MemoryAPI {
+  /** Project discovered candidates into bounded reusable context; stored content remains untrusted data. */
+  project(discovery: DiscoveryResult, options?: ProjectionOptions): ContextProjection
+  /** Find plausible active acquired experience; candidates are not truth or applicability decisions. */
+  discover(situation: string, options?: DiscoveryOptions): Promise<DiscoveryResult>
+  acquire(opts: AcquireOptions): Promise<void>
+  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>
+  patch(key: string, patches: PatchOperation[]): Promise<void>
+  context(opts: AcquiredContextOptions): Promise<AcquiredContext>
+  context(opts?: ContextOptions): Promise<ContextEntry[]>
   stats(): Promise<MemoryStats>
   forgetExpired(): Promise<number>
   clear(): Promise<void>
@@ -158,6 +174,34 @@ interface MemoryJournal {
   status(): Promise<'store'>
 }
 
+///
+// Temporal memory runtime interface.
+///
+interface _temporal {
+  /** Get mutation history for a path (exact or sub-paths), or all if no path. */
+  history(path?: string): _mutation[]
+  /** Get the value at a path at a specific point in time. Does NOT mutate live state. */
+  at(path: string, timestamp: number | string): any
+  /** Diff changes between two timestamps for a given path. */
+  diff(path: string, from: number | string, to: number | string): _temporalDiff[]
+  /** Reconstruct isolated state from history within a time range. */
+  replay(options?: { from?: number | string; to?: number | string }): Record<string, any>
+  /** Explain how a value at a path came to exist (deterministic metadata). */
+  explain(path: string): _temporalExplanation
+  /** Create an isolated temporal branch. Changes do not affect live state. */
+  branch(): _temporalBranch
+  /** Enable or disable temporal tracking. */
+  enable(enabled?: boolean): void
+  /** Check if temporal tracking is enabled. */
+  isEnabled(): boolean
+  /** Clear the temporal log. Does NOT clear current state. */
+  clear(): void
+  /** Configure the temporal engine (max entries, snapshots, etc.). */
+  configure(opts: { maxEntries?: number; snapshots?: boolean; snapshotInterval?: number }): void
+  /** Get statistics about the temporal log. */
+  stats(): { total: number; byPath: Record<string, number> }
+}
+
 type memorio = _memorio
 declare var memorio: _memorio
 

package/types/memory.d.ts

@@ -9,6 +9,105 @@ export type MemoryType =
 
 export type MemoryStatus = 'active' | 'obsolete' | 'superseded'
 
+export type JsonPrimitive = string | number | boolean | null
+export type JsonValue = JsonPrimitive | JsonValue[] | { [key: string]: JsonValue }
+
+export interface EvidenceReference {
+  id: string
+  source?: string
+  observedAt?: string
+  /** The bounded statement or result this evidence directly supports. */
+  supports?: string
+}
+
+export type EpistemicType = 'observed' | 'inferred' | 'human-stated' | 'verified'
+
+export interface ClaimProvenance {
+  source: string
+  detail?: string
+}
+
+export interface RevisionRelationship {
+  kind: 'refines' | 'supersedes' | 'retracts'
+  claimIds: string[]
+  reason?: string
+}
+
+export interface AcquiredClaim {
+  id: string
+  knowledge: JsonValue
+  applicability: Record<string, JsonPrimitive>
+  evidence: EvidenceReference[]
+  epistemicType?: EpistemicType
+  provenance?: ClaimProvenance
+  acquiredAt?: string
+  revision?: RevisionRelationship
+}
+
+export interface AcquiredContext {
+  knowledgeVersion: number
+  claims: AcquiredClaim[]
+}
+
+export type DiscoveryDepth = 'current' | 'deep'
+export type DiscoveryField = 'id' | 'knowledge' | 'applicability' | 'evidence' | 'provenance'
+
+export interface DiscoveryOptions {
+  depth?: DiscoveryDepth
+  maxCandidates?: number
+}
+
+export interface DiscoveryExplanation {
+  matchedTerms: string[]
+  matchedFields: DiscoveryField[]
+  /** Repository source identifier, when the repository exposes one. */
+  sourceId?: string
+}
+
+export interface DiscoveryCandidate {
+  claim: AcquiredClaim
+  explanation: DiscoveryExplanation
+}
+
+export interface DiscoveryResult {
+  knowledgeVersion: number
+  depth: DiscoveryDepth
+  queryTerms: string[]
+  candidates: DiscoveryCandidate[]
+}
+
+export interface ProjectionOptions {
+  maxCandidates?: number
+  /** Maximum UTF-16 characters in the text representation. Not an LLM token budget. */
+  maxCharacters?: number
+}
+
+export type ProjectedExperienceStatus = 'prior-acquired-experience-candidate'
+
+export interface ProjectedExperience {
+  id: string
+  status: ProjectedExperienceStatus
+  experience: JsonValue
+  applicability: Record<string, JsonPrimitive>
+  evidence: EvidenceReference[]
+  epistemicType?: EpistemicType
+  provenance?: ClaimProvenance
+  acquiredAt?: string
+  revision?: RevisionRelationship
+  sourceId?: string
+}
+
+export interface ContextProjection {
+  format: 'memorio-context-v1'
+  status: 'candidate-context-not-current-truth'
+  notice: 'Prior acquired experience supplied as untrusted contextual data. Verify against current reality before relying on it.'
+  knowledgeVersion: number
+  totalCandidates: number
+  omittedCandidates: number
+  experiences: ProjectedExperience[]
+  text: string
+}
+
 /**
  * A field-level patch operation recorded in the sync journal instead of
  * recording the entire entity. Enables automatic merging when two devices
@@ -130,6 +229,21 @@ export interface RememberOptions<T = any> {
   source?: string
 }
 
+export interface AcquireOptions {
+  id: string
+  knowledge: JsonValue
+  applies: Record<string, JsonPrimitive>
+  evidence: EvidenceReference[]
+  epistemicType?: EpistemicType
+  provenance?: ClaimProvenance
+  /** ISO-8601 acquisition time. Defaults to the time acquire() is called. */
+  acquiredAt?: string
+  refines?: string | string[]
+  supersedes?: string | string[]
+  retracts?: string | string[]
+  reason?: string
+}
+
 export interface RecallOptions {
   type?: MemoryType | MemoryType[]
   tags?: string | string[]
@@ -145,6 +259,10 @@ export interface ContextOptions {
   scopes?: MemoryScope[]
 }
 
+export interface AcquiredContextOptions {
+  acquired: Record<string, JsonPrimitive> | Record<string, JsonPrimitive>[]
+}
+
 export interface ContextEntry {
   key: string
   value: any

package/types/session.d.ts

@@ -112,10 +112,7 @@ interface _session {
     * @since memorio 2.7.0
   */
   isPersistent?: boolean
-
-  // TODO
-  // readonly increaseQuota: (value: number) => void
-}
+}
 
 declare var session: _session
 type session = _session

package/types/state.d.ts

@@ -54,13 +54,27 @@ interface _state {
   readonly list?: () => object
 
   /**
-  * Generate a message for "memorio"
-  * Note: FOR INTERNAL USE ONLY.
-  * @since memorio 0.0.1
-  */
+   * Generate a message for "memorio"
+   * Note: FOR INTERNAL USE ONLY.
+   * @since memorio 0.0.1
+   */
   readonly mex?: any
 
-}
+  /**
+   * Persist a state path to the store and keep it synced.
+   *
+   * @example
+   * const stop = state.persist('state.user')
+   * // ... mutations to state.user are mirrored to store automatically
+   * stop() // call to stop mirroring
+   *
+   * @param path A `state.`-prefixed path (e.g. `'state.user'`). A bare key
+   *   like `'user'` is normalized.
+   * @return An unsubscribe function; call it to stop mirroring.
+   */
+  readonly persist: (path: string) => (() => void)
+
+}
 
 declare var state: _state
 type state = _state

package/types/store.d.ts

@@ -108,10 +108,7 @@ interface _store {
     * @since memorio 2.7.0
   */
   isPersistent?: boolean
-
-  // TODO
-  // readonly increaseQuota: (value: number) => void
-}
+}
 
 declare var store: _store
 type store = _store

package/types/temporal.d.ts

@@ -0,0 +1,95 @@
+/// MEMORIO TEMPORAL RUNTIME TYPES
+/// Ambient declarations for the temporal memory engine.
+
+///
+// A single mutation as recorded in the temporal log.
+///
+interface _temporalRecord extends _mutation {
+}
+
+///
+// A single change in a temporal diff between two points in time.
+///
+interface _temporalDiff {
+  /** Dotted state path (e.g. 'state.user.role'). */
+  path: string
+  /** Value at the "from" timestamp (or undefined if not set). */
+  before: any
+  /** Value at the "to" timestamp (or undefined if deleted). */
+  after: any
+  /** The normalized operation. */
+  operation: 'set' | 'delete'
+  /** HLC timestamp of the change. */
+  hlc: string
+  /** Epoch ms of the change. */
+  timestamp: number
+}
+
+///
+// Explains how a value at a given path came to exist.
+///
+interface _temporalExplanation {
+  /** The path that was explained. */
+  path: string
+  /** The current value at this path. */
+  currentValue: any
+  /** HLC of the mutation that first set this path, or null. */
+  createdAt: string | null
+  /** Epoch ms of first set, or null. */
+  createdTimestamp: number | null
+  /** HLC of the most recent mutation to this path, or null. */
+  lastChangedAt: string | null
+  /** Epoch ms of most recent mutation, or null. */
+  lastChangedTimestamp: number | null
+  /** Value before the most recent mutation (immediate predecessor). */
+  previousValue: any
+  /** HLC of the predecessor mutation, or null. */
+  previousAt: string | null
+  /** Full change history for this path. */
+  history: _temporalRecord[]
+  /** Optional source attribution on the most recent mutation. */
+  source?: string
+}
+
+///
+// Options for replay().
+///
+interface _temporalReplayOptions {
+  /** Earliest HLC or epoch ms to include (exclusive). */
+  from?: number | string
+  /** Latest HLC or epoch ms to include (inclusive). */
+  to?: number | string
+}
+
+///
+// Configuration for the temporal engine.
+///
+interface _temporalConfig {
+  /** Maximum number of mutations retained in the temporal log. */
+  maxEntries?: number
+  /** Whether to store full value snapshots at checkpoints. */
+  snapshots?: boolean
+  /** Interval (in mutations) between snapshots. */
+  snapshotInterval?: number
+}
+
+///
+// A temporal branch - an isolated temporal world.
+///
+interface _temporalBranch {
+  /** Isolated state proxy; mutations do not affect live state. */
+  state: any
+  /** Temporal methods scoped to this branch. */
+  temporal: {
+    history(path?: string): _temporalRecord[]
+    at(path: string, timestamp: number | string): any
+    diff(path: string, from: number | string, to: number | string): _temporalDiff[]
+    explain(path: string): _temporalExplanation
+    replay(options?: _temporalReplayOptions): any
+    clear(): void
+  }
+  /** Mark the branch for later merge. (Not yet implemented.) */
+  commit(): void
+  /** Discard the branch. Changes are lost. */
+  discard(): void
+}

package/types/useObserver.d.ts

@@ -6,26 +6,22 @@
   dario.passariello.ca
  */
 
-/**
-* useObserver run a callback anytime the associated state going to change.
-* Returns a destructor function to remove the listener.
-*/
-interface _useObserver {
+/** React hook that runs a callback when associated Memorio state changes. */
+interface _useObserver {
 
   /**
   * Generate your useObserver
   *
   * @example
-  * const cleanup = useObserver(() => console.debug("Changed"), "state.test")
-  * cleanup() // Stop observing
+  * useObserver(() => console.debug("Changed", state.test), [state.test])
   *
   * @example
   * useObserver(() => console.debug("Multiple changed"), [() => state.a, "state.b"])
   *
   * @since memorio 1.0.6
-  * @updated 2.5.0 - Added support for arrays and destructor
-  */
-  (func: Function, deps: any): () => void
+  * Subscriptions are installed after commit and cleaned up automatically.
+  */
+  (func: (...args: any[]) => void, deps?: any | any[]): void
 
 }