@mzhub/mem-ts 0.1.0

package/dist/types-G9qmfSeZ.d.ts

@@ -0,0 +1,260 @@
+/**
+ * Core type definitions for mem-ts Memory OS
+ */
+/**
+ * A single memory fact representing a relationship between entities
+ */
+interface MemoryFact {
+    /** Unique identifier (UUID) */
+    id: string;
+    /** The entity (e.g., "User", "Project:WebApp") */
+    subject: string;
+    /** The relationship (e.g., "HAS_ALLERGY", "PREFERS", "WORKS_AT") */
+    predicate: string;
+    /** The value (e.g., "Peanuts", "Dark Mode", "Acme Corp") */
+    object: string;
+    /** Confidence score 0-1 */
+    confidence: number;
+    /**
+     * Importance score 1-10 (Amygdala pattern)
+     * 1-3: Trivia (preferences, minor details)
+     * 4-6: Standard (work, location, relationships)
+     * 7-8: Important (strong preferences, constraints)
+     * 9-10: Critical (allergies, safety, medical, boundaries)
+     */
+    importance: number;
+    /** Conversation ID that created/updated this fact */
+    source: string;
+    /** Specific conversation exchange ID for episodic linking */
+    sourceConversationId?: string;
+    /** When this fact was first created */
+    createdAt: Date;
+    /** When this fact was last updated */
+    updatedAt: Date;
+    /** When this fact was superseded (null if still valid) */
+    invalidatedAt: Date | null;
+    /** Number of times this fact has been accessed (Hebbian learning) */
+    accessCount?: number;
+    /** Last time this fact was accessed */
+    lastAccessedAt?: Date;
+    /**
+     * Emotional context when fact was learned (Emotional Coloring)
+     * Tracks whether the fact was learned in a positive or negative context
+     */
+    sentiment?: "positive" | "negative" | "neutral";
+    /** Description of the emotional context */
+    emotionalContext?: string;
+    /**
+     * Memory consolidation stage (Memory Consolidation Levels)
+     * - short-term: Just learned, may not persist
+     * - working: Being actively used, intermediate storage
+     * - long-term: Consolidated through reinforcement
+     */
+    memoryStage?: "short-term" | "working" | "long-term";
+    /**
+     * IDs of related facts (Associative Linking / Knowledge Graph)
+     * Creates connections between facts for richer context
+     */
+    relatedFactIds?: string[];
+    /**
+     * Vector embedding for semantic search (Attention Filtering)
+     * Stored as array of numbers for similarity matching
+     */
+    embedding?: number[];
+    /**
+     * Memory level in the hierarchy pyramid:
+     * - raw_log: Raw conversation data (ephemeral, auto-deleted)
+     * - fact: Specific discrete facts (your normal facts)
+     * - pattern: Synthesized patterns/traits from multiple facts
+     * - core_belief: Unchangeable truths, always loaded (allergies, identity)
+     */
+    memoryLevel?: "raw_log" | "fact" | "pattern" | "core_belief";
+    /**
+     * IDs of lower-level facts that this pattern/belief was derived from.
+     * Creates provenance chain for "why do I believe this?"
+     */
+    childrenIds?: string[];
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * A memory operation for updating the fact graph
+ */
+interface MemoryOperation {
+    /** Operation type */
+    op: "INSERT" | "UPDATE" | "DELETE";
+    /** The entity */
+    subject: string;
+    /** The relationship */
+    predicate: string;
+    /** The value */
+    object: string;
+    /** Reason for this operation (especially for DELETEs) */
+    reason?: string;
+    /** Confidence score 0-1 */
+    confidence?: number;
+    /** Importance score 1-10 (for safety-critical facts) */
+    importance?: number;
+    /** Sentiment context when fact was learned */
+    sentiment?: "positive" | "negative" | "neutral";
+}
+/**
+ * Result from the fact extraction LLM
+ */
+interface ExtractionResult {
+    /** List of operations to apply */
+    operations: MemoryOperation[];
+    /** Reasoning for the extractions */
+    reasoning?: string;
+}
+/**
+ * A single message in a conversation
+ */
+interface Message {
+    role: "user" | "assistant" | "system";
+    content: string;
+    timestamp: Date;
+}
+/**
+ * A conversation exchange (user message + assistant response)
+ */
+interface ConversationExchange {
+    id: string;
+    userId: string;
+    sessionId: string;
+    userMessage: string;
+    assistantResponse: string;
+    timestamp: Date;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Session information
+ */
+interface Session {
+    id: string;
+    userId: string;
+    startedAt: Date;
+    endedAt: Date | null;
+    messageCount: number;
+    summary?: string;
+}
+/**
+ * Result from hydrating context before an LLM call
+ */
+interface HydratedContext {
+    /** Compiled prompt ready for injection into system message */
+    compiledPrompt: string;
+    /** Raw facts that were retrieved */
+    facts: MemoryFact[];
+    /** Recent conversation history */
+    recentHistory: ConversationExchange[];
+    /** Token estimate for the compiled context */
+    estimatedTokens: number;
+    /** Whether this was served from cache */
+    fromCache: boolean;
+}
+/**
+ * Options for hydration
+ */
+interface HydrateOptions {
+    /** Maximum number of facts to include */
+    maxFacts?: number;
+    /** Maximum number of recent messages to include */
+    maxHistory?: number;
+    /** Specific predicates to filter for */
+    predicates?: string[];
+    /** Whether to include invalidated facts */
+    includeInvalidated?: boolean;
+}
+/**
+ * Options for LLM completion
+ */
+interface CompletionOptions {
+    /** System prompt */
+    systemPrompt: string;
+    /** User prompt */
+    userPrompt: string;
+    /** Maximum tokens in response */
+    maxTokens?: number;
+    /** Temperature (0-1, lower = more deterministic) */
+    temperature?: number;
+    /** Force JSON output mode */
+    jsonMode?: boolean;
+}
+/**
+ * Result from LLM completion
+ */
+interface CompletionResult {
+    /** The generated content */
+    content: string;
+    /** Token usage */
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+    };
+}
+/**
+ * Supported LLM providers
+ */
+type ProviderName = "openai" | "anthropic" | "gemini" | "groq" | "cerebras";
+/**
+ * LLM provider configuration
+ */
+interface ProviderConfig {
+    /** Provider name */
+    provider: ProviderName;
+    /** API key */
+    apiKey: string;
+    /** Model to use (each provider has its own default) */
+    model?: string;
+    /** Base URL override (for proxies or self-hosted) */
+    baseUrl?: string;
+}
+/**
+ * Filter options for querying facts
+ */
+interface FactFilter {
+    /** Filter by subject */
+    subject?: string;
+    /** Filter by predicate */
+    predicate?: string;
+    /** Filter by predicates (OR) */
+    predicates?: string[];
+    /** Only valid (non-invalidated) facts */
+    validOnly?: boolean;
+    /** Limit number of results */
+    limit?: number;
+    /** Order by field */
+    orderBy?: "createdAt" | "updatedAt" | "confidence";
+    /** Order direction */
+    orderDir?: "asc" | "desc";
+}
+/**
+ * Options for MemoryOS behavior
+ */
+interface MemoryOSOptions {
+    /** Auto-summarize conversations after this many messages */
+    autoSummarizeAfter?: number;
+    /** Conflict resolution strategy */
+    conflictStrategy?: "latest" | "merge" | "keep_both";
+    /** Enable semantic caching */
+    enableCache?: boolean;
+    /** Cache TTL in seconds */
+    cacheTtl?: number;
+    /** Debug mode */
+    debug?: boolean;
+}
+/**
+ * Events emitted by MemoryOS
+ */
+interface MemoryOSEvents {
+    "fact:created": (fact: MemoryFact) => void;
+    "fact:updated": (fact: MemoryFact, oldFact: MemoryFact) => void;
+    "fact:deleted": (fact: MemoryFact, reason: string) => void;
+    "session:start": (session: Session) => void;
+    "session:end": (session: Session) => void;
+    "extraction:complete": (result: ExtractionResult) => void;
+    error: (error: Error) => void;
+}
+
+export type { ConversationExchange as C, ExtractionResult as E, FactFilter as F, HydrateOptions as H, MemoryFact as M, ProviderConfig as P, Session as S, CompletionOptions as a, CompletionResult as b, MemoryOSOptions as c, HydratedContext as d, ProviderName as e, MemoryOperation as f, Message as g, MemoryOSEvents as h };

package/package.json

@@ -0,0 +1,114 @@
+{
+  "name": "@mzhub/mem-ts",
+  "version": "0.1.0",
+  "description": "Persistent memory for AI agents - A tiered memory system with fact extraction and conflict resolution",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    },
+    "./adapters": {
+      "types": "./dist/adapters/index.d.ts",
+      "import": "./dist/adapters/index.mjs",
+      "require": "./dist/adapters/index.js"
+    },
+    "./providers": {
+      "types": "./dist/providers/index.d.ts",
+      "import": "./dist/providers/index.mjs",
+      "require": "./dist/providers/index.js"
+    },
+    "./middleware": {
+      "types": "./dist/middleware/index.d.ts",
+      "import": "./dist/middleware/index.mjs",
+      "require": "./dist/middleware/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "logo.png"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest",
+    "test:run": "vitest run",
+    "lint": "eslint src",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "ai",
+    "memory",
+    "llm",
+    "agents",
+    "knowledge-graph",
+    "context",
+    "openai",
+    "anthropic",
+    "gemini",
+    "groq",
+    "cerebras",
+    "ai-memory",
+    "chatbot-memory"
+  ],
+  "author": "MZ Hub",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/MZ-Hub/mem-ts.git"
+  },
+  "homepage": "https://github.com/MZ-Hub/mem-ts#readme",
+  "bugs": {
+    "url": "https://github.com/MZ-Hub/mem-ts/issues"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "@types/uuid": "^10.0.0",
+    "tsup": "^8.5.1",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.9"
+  },
+  "dependencies": {
+    "uuid": "^11.0.3"
+  },
+  "peerDependencies": {
+    "@anthropic-ai/sdk": "^0.30.0",
+    "@cerebras/cerebras_cloud_sdk": "^1.0.0",
+    "@google/generative-ai": ">=0.21.0",
+    "groq-sdk": "^0.8.0",
+    "openai": "^4.0.0",
+    "mongodb": "^6.0.0",
+    "pg": "^8.0.0"
+  },
+  "peerDependenciesMeta": {
+    "openai": {
+      "optional": true
+    },
+    "@anthropic-ai/sdk": {
+      "optional": true
+    },
+    "@google/generative-ai": {
+      "optional": true
+    },
+    "groq-sdk": {
+      "optional": true
+    },
+    "@cerebras/cerebras_cloud_sdk": {
+      "optional": true
+    },
+    "mongodb": {
+      "optional": true
+    },
+    "pg": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}