dotmem 0.0.1 → 0.0.3

package/package.json

@@ -1,72 +1,92 @@
 {
   "name": "dotmem",
   "codeName": "dotmem",
-  "version": "0.0.1",
-  "description": "Append your component in any part of your html using reattach",
-  "license": "PROPRIETARY",
-  "author": "Dario Passariello",
-  "main": "./index.js",
-  "module": "./index.mjs",
+  "version": "0.0.3",
+  "license": "MIT",
+  "type": "module",
+  "description": "The AI memory layer for agents and apps: acquired experience, discovery, context projection, continuity, and logic engine. Built on dotmem's state+store foundation.",
+  "main": "./index.cjs",
+  "module": "./index.js",
   "types": "./index.d.ts",
-  "typings": "./index.d.ts",
   "exports": {
     ".": {
-      "types": "./index.d.ts",
-      "import": "./index.mjs",
-      "require": "./index.js"
+      "import": "./index.js",
+      "require": "./index.cjs",
+      "types": "./index.d.ts"
+    },
+    "./global": {
+      "import": "./global.js",
+      "require": "./global.cjs",
+      "types": "./global.d.ts"
     },
-    "./types/*": "./types/*"
+    "./agent": {
+      "import": "./agent.js",
+      "require": "./agent.cjs"
+    }
   },
-  "files": [
-    "index.js",
-    "index.mjs",
-    "index.d.ts",
-    "types",
-    "AGENTS.md",
-    "CITATION.md",
-    "CODEOWNERS.md",
-    "COPYRIGHT.md",
-    "LICENSE.md",
-    "llms.txt",
-    "README.md",
-    "SECURITY.md"
+  "copyright": "Dario Passariello",
+  "author": "Dario Passariello - <dariopassariello@gmail.com>",
+  "contributors": [
+    {
+      "name": "Dario Passariello",
+      "email": "dariopassarielloa@gmail.com"
+    },
+    {
+      "name": "Valeria Cala Scaglitta",
+      "email": "valeriacalascaglitta@gmail.com"
+    }
+  ],
+  "bin": {
+    "dotmem": "./bin/cli.js",
+    "dotmem-mcp": "./bin/mcp.js"
+  },
+  "workspaces": [
+    "tests"
   ],
   "keywords": [
     ".mem",
+    "dotmem",
+    "ai-agent",
+    "agent-memory",
+    "acquired-experience",
     "memory",
-    "joy",
-    "jo",
+    "continuity",
+    "knowledge",
     "mcp",
-    "ai",
-    "agents",
-    "assistant"
+    "joytrend",
+    "joy",
+    "jo"
   ],
-  "scripts": {
-    "build": "tsup",
-    "npm:publish": "npm run build && npm publish ./dist",
-    "": "-----------",
-    "lint": "cd tests && npm run lint",
-    "tsc": "cd tests && npm run tsc",
-    "test": "cd tests && npm run test",
-    "test:coverage": "cd tests && npm run test:coverage",
-    "pw": "cd tests && npm run pw",
-    "pw:browser": "cd tests && npm run pw"
+  "engines": {
+    "node": ">=18.0.0"
   },
-  "peerDependencies": {
-    "react": "^18.0.0 || ^19.0.0",
-    "react-dom": "^18.0.0 || ^19.0.0"
+  "files": [
+    "types/**/*",
+    "modules/**/*",
+    "template/**/*",
+    "index.d.ts",
+    "global.d.ts",
+    "**/*.js",
+    "**/*.cjs",
+    "**/*.md",
+    "**/*.txt"
+  ],
+  "publishConfig": {
+    "access": "public"
   },
-  "engines": {
-    "node": ">=18"
+  "optionalDependencies": {
+    "@modelcontextprotocol/server": "^2.4.0",
+    "zod": "^4.6.7"
+  },
+  "overrides": {
+    "glob": "^14.0.2",
+    "minimatch": "^11.0.1"
+  },
+  "typings": "./index.d.ts",
+  "scripts": {
+    "prepack": "node -e \"['bin/cli.js','bin/cli.cjs','bin/mcp.js','bin/mcp.cjs'].forEach(f=>{try{require('fs').chmodSync(f,0o755)}catch{}})\""
   },
-  "devDependencies": {
-    "@types/node": "26.6.5",
-    "react": "^19.3.1",
-    "react-dom": "^19.3.1",
-    "terser": "5.51.2",
-    "tslib": "^2.8.1",
-    "tsup": "^9.0.0",
-    "tsx": "4.23.15",
-    "typescript": "7.0.2"
+  "dependencies": {
+    "dotmem": ">=0.0.1"
   }
 }

package/types/agent.d.ts

@@ -0,0 +1,87 @@
+/**
+ * DOTMEM AGENT DECLARATIONS
+ *
+ * Mirrors the agent-facing memory API exported from `dotmem/agent`.
+ * Every agent gets an isolated namespace: keys are stored as
+ * `agent:<agentId>:<key>` and entries are tagged with the agent id, so two
+ * agents never share private memory by accident.
+ */
+
+import type {
+  ContextEntry,
+  MemoryEntry,
+  MemoryScope,
+  MemoryStats,
+  MemoryType,
+  RecallOptions
+} from './memory'
+
+export interface AgentContextOptions {
+  tags?: string | string[]
+  types?: MemoryType | MemoryType[]
+  minConfidence?: number
+  maxEntries?: number
+  scopes?: MemoryScope[]
+}
+
+export interface AgentRememberOptions {
+  type?: MemoryType
+  confidence?: number
+  scope?: MemoryScope
+  ttl?: number | null
+  tags?: string[]
+  source?: string
+}
+
+export interface AgentReplayOptions {
+  from: number | string
+  to: number | string
+}
+
+export interface AgentBranchState {
+  state: Record<string, unknown>
+  temporal: {
+    history: (path?: string) => MemoryEntry[]
+    at: (path: string, timestamp: string | number) => unknown
+    diff: (path: string, from: string | number, to: string | number) => MemoryEntry[]
+    replay: (opts?: { from?: string | number; to?: string | number }) => Record<string, unknown>
+    explain: (path: string) => unknown
+    branch: () => AgentBranchState
+    discard: () => void
+  }
+}
+
+export interface AgentMemory {
+  /** Identifier of the agent owning this isolated namespace. */
+  readonly agentId: string
+  /** Store a memory entry, namespaced and tagged for this agent. */
+  remember: (key: string, value: unknown, options?: AgentRememberOptions) => Promise<void>
+  /** Read a memory entry by key. Expired, obsolete, and superseded entries are null. */
+  recall: (key: string, options?: RecallOptions) => Promise<MemoryEntry | null>
+  /** Ranked memories for this agent only. Additional tags use AND semantics. */
+  context: (options?: AgentContextOptions) => Promise<ContextEntry[]>
+  /** Mutation history, optionally for one path. */
+  history: (path?: string) => Promise<MemoryEntry[]>
+  /** Replay the state evolution over a temporal range. */
+  replay: (opts: AgentReplayOptions) => Promise<Record<string, unknown>>
+  /** Open an isolated temporal branch for experimentation. */
+  branch: () => Promise<AgentBranchState>
+  /** Memory usage statistics. */
+  stats: () => Promise<MemoryStats>
+  /** Update an existing memory entry. */
+  update: (key: string, value: unknown, options?: AgentRememberOptions) => Promise<void>
+  /** Delete a memory entry. */
+  forget: (key: string) => Promise<void>
+  /** Enable temporal and history tracking. */
+  enable: (bool?: boolean) => Promise<void>
+  /** Disable temporal tracking. */
+  disable: () => Promise<void>
+  /** Clear the temporal log and every memory of this agent. */
+  clear: () => Promise<void>
+}
+
+/** Create an agent-specific memory instance with an isolated namespace. */
+export declare function createAgentMemory(agentId: string): AgentMemory
+
+/** Create an agent memory instance with the default agent id. */
+export declare function createDefaultAgentMemory(): AgentMemory

package/types/assets.d.ts

@@ -0,0 +1,4 @@
+declare module '*.md' {
+  const content: string
+  export default content
+}

package/types/bun-sqlite.d.ts

@@ -0,0 +1,14 @@
+declare module 'bun:sqlite' {
+  export class Database {
+    constructor(path: string)
+    run(sql: string, ...params: any[]): any
+    query(sql: string): { all(...params: any[]): any[]; get(...params: any[]): any }
+    close(): void
+    prepare(sql: string): { all(...params: any[]): any[]; get(...params: any[]): any }
+  }
+  export class Statement {
+    all(...params: any[]): any[]
+    get(...params: any[]): any
+    run(...params: any[]): any
+  }
+}

package/types/exports.d.ts

@@ -0,0 +1,285 @@
+export * from './memory'
+export * from './agent'
+export * from './logic'
+export * from './policy'
+export * from './profile'
+export * from './llm-cache'
+
+// ── Memory facade type ───────────────────────────────────────────────────
+export interface MemoryFacade {
+  init(): Promise<void>
+  discover(situation: string | import('./memory').Situation, options?: import('./memory').DiscoveryOptions): Promise<import('./memory').DiscoveryResult>
+  context(options?: ContextQueryOptions): Promise<import('./memory').AcquiredContext>
+  project(discovery: import('./memory').DiscoveryResult, options?: import('./memory').ProjectionOptions): import('./memory').ContextProjection
+  acquire(opts: import('./memory').AcquireOptions): Promise<void>
+  acquireStaged(opts: import('./memory').AcquireOptions): Promise<void>
+  remember<T>(key: string, value: T, opts?: import('./memory').RememberOptions<T>): Promise<void>
+  recall<T = any>(query: string | number, opts?: import('./memory').RecallOptions): Promise<T | null>
+  update(key: string, value: any, opts?: Partial<import('./memory').RememberOptions>): Promise<void>
+  forget(key: string): Promise<void>
+  patch(key: string, patches: import('./memory').PatchOperation[]): Promise<void>
+  stats(): Promise<import('./memory').MemoryStats>
+  forgetExpired(): Promise<number>
+  clear(): Promise<void>
+  fingerprint(): Promise<string>
+  journal: MemoryJournal
+  profile: MemoryProfile
+  note: MemoryNotes
+  seed: MemorySeed
+  policy: MemoryPolicyAPI
+  brain: MemoryBrainAPI
+  configure(config: import('./memory').SyncConfig): void
+  configureSync(config: import('./memory').SyncConfig): void
+  resetBrainPathCache(): void
+  resetPolicyStoreCache(): void
+  _getEntry(key: string): Promise<import('./memory').MemoryEntry | null>
+  _loadAll(): Promise<import('./memory').MemoryEntry[]>
+  _save(entry: import('./memory').MemoryEntry): Promise<void>
+}
+
+export interface LlmCacheAPI {
+  llm<T>(opts: import('./llm-cache').LlmCacheOptions<T>): Promise<import('./llm-cache').LlmCacheResult<T>>
+  llmStats(): import('./llm-cache').LlmCacheStats
+  llmPurge(selector: import('./llm-cache').LlmCachePurgeSelector): number
+  [key: string]: any
+}
+
+type Situation = string
+
+export interface ContextQueryOptions {
+  tags?: string | string[]
+  types?: import('./memory').MemoryType | import('./memory').MemoryType[]
+  minConfidence?: number
+  maxEntries?: number
+  scopes?: import('./memory').MemoryScope[]
+  project?: boolean
+}
+
+export interface MemoryJournal {
+  read: (opts?: { limit?: number }) => Promise<JournalEntry[]>
+  write: (entry: JournalEntry | JournalEntry[]) => Promise<void>
+  clear: () => Promise<void>
+}
+
+export interface JournalEntry {
+  id: string
+  key: string
+  type: import('./memory').MemoryType
+  operation: string
+  hlc?: string
+  createdAt: number
+  payload?: unknown
+}
+
+export interface MemoryProfile {
+  get(): import('./profile').DotMemProfile
+}
+
+export interface MemoryNotes {
+  add(text: string, opts?: { id?: string; tags?: string[] }): Promise<void>
+  get(id: string): Promise<NoteContent | null>
+  list(): Promise<NoteEntry[]>
+  forget(id: string): Promise<void>
+}
+
+export interface NoteContent {
+  id: string
+  title: string
+  content: string
+  tags: string[]
+  createdAt: number
+  sha256: string
+}
+
+export interface NoteEntry {
+  id: string
+  title: string
+  size: number
+  sha256: string
+  origin: string
+  tag?: string
+  acquiredAt?: string
+  scope?: string
+  type?: import('./memory').MemoryType
+  version?: number
+  updatedAt?: number
+  previousId?: string | null
+  patches?: import('./memory').PatchOperation[]
+  hlc?: string
+  key?: string
+  value?: unknown
+  status?: string
+  createdAt?: number
+  lastConfirmedAt?: number
+  supersededId?: string | null
+  confidence?: number
+  source?: string
+  ttl?: number | null
+}
+
+export interface MemorySeed {
+  id: string
+  title: string
+  content: string
+  origin: string
+}
+
+// ── dotmem public runtime exports ────────────────────────────────────────
+declare const memory: MemoryFacade
+declare const logic: any
+declare const continuity: any
+declare const security: any
+
+// ── User identity surface ────────────────────────────────────────────────
+export interface UserIdentity {
+  id: string
+  name?: string
+  email?: string
+}
+declare function resolveUserIdentity(): UserIdentity | null
+declare function setUserIdentity(id: string, identity: UserIdentity): void
+declare function clearUserIdentity(): void
+
+// ── User paths surface ───────────────────────────────────────────────────
+declare function resolveUserDotMemPath(): string
+declare function resolveUserProjectMemoryPath(projectId?: string): string
+declare function resolveUserAnchor(): string
+declare function resolveUserBrainPath(): string
+declare function resolveUserContractPath(): string
+declare function resolveUserAgentMemoryPath(): string
+declare function resolveUserReadmePath(): string
+declare function resolveUserExperiencePath(): string
+
+// ── Storage location surface ─────────────────────────────────────────────
+export interface DotMemStorageLocationError extends Error {
+  readonly storageRoot: string
+  readonly source: string
+}
+declare const DOTMEM_STORAGE_ROOT_ENV_VAR: string
+declare const DOTMEM_USER_ANCHOR_DIR_NAME: string
+declare const DOTMEM_STORAGE_LOCATOR_FILE_NAME: string
+declare const DOTMEM_STORAGE_LOCATOR_VERSION: number
+declare function resolveDotMemStorageRoot(): string
+declare function describeDotMemStorage(): unknown
+declare function readDotMemStorageLocator(): unknown
+declare function relocateDotMemStorage(target: string): unknown
+declare function restoreDefaultDotMemStorage(): unknown
+
+// ── Project identity surface ─────────────────────────────────────────────
+declare function resolveProjectIdentity(id?: string): Promise<string>
+
+// ── Mem package inspection ──────────────────────────────────────────────
+declare function inspectMem(mem: unknown, opts?: Record<string, unknown>): unknown
+declare function signMemPackage(mem: unknown, key: unknown): unknown
+export interface MemInspection {
+  status: 'inspected'
+  version: number
+  entries: unknown[]
+}
+export interface MemInspectionStatus {
+  valid: boolean
+  errors?: string[]
+}
+
+// ── Profile ──────────────────────────────────────────────────────────────
+export interface DotMemProfileDocument {
+  readonly name: string
+  readonly content: string
+}
+export interface DotMemProfile {
+  readonly format: 'dotmem.profile'
+  readonly version: 1
+  readonly id: 'joy'
+  readonly name: 'Joy'
+  readonly alternative: ['Jo']
+  readonly documents: ReadonlyArray<DotMemProfileDocument>
+  readonly type: 'ai-persona'
+  readonly role: string
+  readonly immutable: true
+  readonly description: string
+}
+declare const JO_PROFILE: Readonly<DotMemProfile>
+
+// ── Mutation engine extras ──────────────────────────────────────────────
+declare function currentTimestamp(): string
+declare function activeTransactionId(): string | null
+
+// ── Foundation re-exports (runtime values) from memorio ──────────────────
+declare const state: any
+declare const store: any
+declare const session: any
+declare const cache: LlmCacheAPI
+declare const idb: any
+declare const sqlite: any
+declare const observer: any
+declare const schema: any
+declare function registerSchema(path: string, schema: any): void
+declare function validate(path: string, value: any): { valid: boolean; errors?: string[] }
+declare function unregisterSchema(path: string): boolean
+declare function listSchemas(): string[]
+declare const typed: <T extends Record<string, any>>() => T
+declare const computed: any
+declare const broadcast: any
+declare const message: (...args: unknown[]) => void
+declare const logger: any
+declare const snapshot: () => Record<string, any>
+declare function diff(snap: Record<string, any>): Array<{ path: string; oldValue: any; newValue: any }>
+declare function undo(): any
+declare function redo(): any
+declare function canUndo(): boolean
+declare function canRedo(): boolean
+declare function rollback(snap: Record<string, any>): void
+declare function trace(): any[]
+declare function enableHistory(enabled?: boolean): void
+declare function clearHistory(): void
+declare function clearRedo(): void
+declare function createMutation(path: string, operation: any, before: any, after: any, opts?: { context?: string; source?: string; transactionId?: string }): unknown
+declare function recordMutation(mutation: unknown): void
+declare function toPatch(mutation: unknown): unknown | null
+declare function mutate(path: string, value: any, opts?: { source?: string; transactionId?: string }): unknown
+declare function beginTransaction(source?: string, message?: string, metadata?: Record<string, any>): unknown
+declare function commitTransaction(): unknown
+declare function abortTransaction(): unknown
+declare function currentTransaction(): unknown
+declare function listTransactions(): unknown[]
+declare const transaction: (source?: string, message?: string, metadata?: Record<string, any>) => unknown
+declare function generateMutationId(): string
+declare function generateTransactionId(): string
+declare function generateCommitId(): string
+declare function mutationToPatch(mutation: unknown): unknown | null
+declare function diffToPatch(path: string, before: any, after: any): unknown | null
+declare function canMerge(p1: unknown, p2: unknown): boolean
+declare function mergePatches(p1: unknown, p2: unknown): unknown
+declare function dispatch(event: string, payload?: unknown): Promise<void>
+declare function isDotMemCodename(value: string): boolean
+declare function codenameKeyFor(value: string): string | undefined
+declare function renderCodenames(): string
+declare const CODENAMES: Record<string, string>
+declare const CODENAME_DETAILS: Record<string, unknown>
+declare function propertyName(container: any, object: any): string | null
+declare const internal: any
+declare function setContext(id: string): void
+declare function getContext(): string | null
+declare const hlc: any
+declare const fractional: any
+declare const encryption: any
+declare const securityEncryption: any
+declare const devtools: any
+declare function help(): void
+declare const temporal: any
+declare const events: Record<string, any>
+declare const dotmem: any
+declare const DEV: boolean
+declare const PROD: boolean
+declare function isBrowser(): boolean
+declare function isNode(): boolean
+declare function isDeno(): boolean
+declare function isBun(): boolean
+declare function isEdge(): boolean
+declare function getCapabilities(): unknown
+declare function createContext(name?: string, opts?: { encryptionKey?: any }): unknown
+declare function listContexts(): unknown[]
+declare function deleteContext(id: string): void
+declare function isolate(name?: string, opts?: { encryptionKey?: any }): void
+
+export default dotmem

package/types/fflate-browser.d.ts

@@ -0,0 +1,7 @@
+declare module 'fflate/browser' {
+  export {
+    Unzip,
+    UnzipInflate,
+    zipSync
+  } from 'fflate'
+}

package/types/inspect.d.ts

@@ -0,0 +1,14 @@
+/// DOTMEM 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/llm-cache.d.ts

@@ -0,0 +1,53 @@
+///
+// LLM RESPONSE CACHE TYPES
+// Opt-in token-avoidance cache for LLM responses.
+///
+
+export type LlmCacheScope = 'session' | 'persist'
+
+export type LlmCacheMatchedBy = 'exact' | 'normalized' | 'embedding'
+
+export interface LlmCacheOptions<T = any> {
+  key: {
+    prompt: string
+    model: string
+    params?: Record<string, unknown>
+    context?: string
+  }
+  compute: () => Promise<T>
+  ttl?: string | number
+  scope?: LlmCacheScope
+  cacheable?: boolean | ((value: T) => boolean)
+  deterministicOnly?: boolean
+  similarity?: {
+    mode: 'off' | 'normalized' | 'embedding'
+    threshold?: number
+    embed?: (text: string) => Promise<number[]>
+  }
+  estimateTokens?: (value: T) => number
+}
+
+export interface LlmCacheResult<T = any> {
+  value: T
+  hit: boolean
+  matchedBy?: LlmCacheMatchedBy
+  score?: number
+  key: string
+  createdAt: number
+  savedTokens?: number
+  provenance: 'CACHED' | 'FRESH'
+}
+
+export interface LlmCacheStats {
+  hits: number
+  misses: number
+  savedTokens: number
+  entries: number
+}
+
+export interface LlmCachePurgeSelector {
+  key?: string
+  model?: string
+  olderThan?: string
+  all?: true
+}