dotmem 0.0.1 → 0.0.2

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
+}

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 declare 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
+}
+
+declare const logic: LogicEngine
+export default logic