@mzhub/mem-ts 0.1.0

package/dist/index-Dl-Q2au9.d.ts

@@ -0,0 +1,289 @@
+import { P as ProviderConfig, c as MemoryOSOptions, H as HydrateOptions, d as HydratedContext, E as ExtractionResult, F as FactFilter, M as MemoryFact, S as Session, C as ConversationExchange } from './types-G9qmfSeZ.js';
+import { B as BaseAdapter } from './BaseAdapter-CQVX-gcA.js';
+import { B as BaseProvider } from './BaseProvider-CEoiLGj5.js';
+
+interface MemoryOSConfig {
+    /** LLM provider configuration or instance */
+    llm: ProviderConfig | {
+        instance: BaseProvider;
+    };
+    /** Storage adapter instance */
+    adapter?: BaseAdapter;
+    /** Behavioral options */
+    options?: MemoryOSOptions;
+}
+/**
+ * MemoryOS - The main orchestrator for AI agent memory.
+ *
+ * Implements the "Two-Brain" architecture:
+ * - Fast Brain: Synchronous context retrieval before LLM calls
+ * - Slow Brain: Asynchronous fact extraction after responses
+ *
+ * @example
+ * ```typescript
+ * import { MemoryOS } from 'mem-ts';
+ * import { JSONFileAdapter } from 'mem-ts/adapters';
+ *
+ * const memory = new MemoryOS({
+ *   llm: { provider: 'openai', apiKey: 'sk-...', model: 'gpt-4o-mini' },
+ *   adapter: new JSONFileAdapter({ path: './.mem-ts' })
+ * });
+ *
+ * // Before LLM call - get context
+ * const context = await memory.hydrate(userId, userMessage);
+ *
+ * // After LLM response - extract facts (non-blocking)
+ * memory.digest(userId, userMessage, assistantResponse);
+ * ```
+ */
+declare class MemoryOS {
+    private adapter;
+    private provider;
+    private extractor;
+    private hydrator;
+    private options;
+    private initialized;
+    private activeSessions;
+    constructor(config: MemoryOSConfig);
+    /**
+     * Initialize the memory system (connects to storage, etc.)
+     */
+    initialize(): Promise<void>;
+    /**
+     * Ensure the system is initialized
+     */
+    private ensureInitialized;
+    /**
+     * Hydrate context for injection into an LLM prompt.
+     *
+     * This is the "Fast Brain" - runs synchronously before each LLM call
+     * to provide relevant context from the user's memory.
+     *
+     * @param userId - Unique identifier for the user
+     * @param message - The user's current message (used for relevance ranking)
+     * @param options - Optional filtering and limiting options
+     * @returns Compiled context ready for injection
+     *
+     * @example
+     * ```typescript
+     * const context = await memory.hydrate(userId, userMessage);
+     *
+     * const response = await openai.chat.completions.create({
+     *   messages: [
+     *     { role: 'system', content: `Context: ${context.compiledPrompt}` },
+     *     { role: 'user', content: userMessage }
+     *   ]
+     * });
+     * ```
+     */
+    hydrate(userId: string, message: string, options?: HydrateOptions): Promise<HydratedContext>;
+    /**
+     * Digest a conversation exchange to extract facts.
+     *
+     * This is the "Slow Brain" - runs asynchronously in the background
+     * after a response is sent to the user. Does not block.
+     *
+     * @param userId - Unique identifier for the user
+     * @param userMessage - What the user said
+     * @param assistantResponse - What the assistant replied
+     *
+     * @example
+     * ```typescript
+     * // Fire and forget - doesn't block
+     * memory.digest(userId, userMessage, response.content);
+     *
+     * // Return response to user immediately
+     * res.json({ message: response.content });
+     * ```
+     */
+    digest(userId: string, userMessage: string, assistantResponse: string): void;
+    /**
+     * Extract facts immediately (synchronous version of digest).
+     * Useful for testing or when you need the extraction result.
+     */
+    digestSync(userId: string, userMessage: string, assistantResponse: string): Promise<ExtractionResult>;
+    /**
+     * Get all facts for a user
+     */
+    getFacts(userId: string, filter?: FactFilter): Promise<MemoryFact[]>;
+    /**
+     * Add a fact directly (bypasses extraction)
+     */
+    addFact(userId: string, subject: string, predicate: string, object: string, confidence?: number, importance?: number): Promise<MemoryFact>;
+    /**
+     * Delete a fact
+     */
+    deleteFact(userId: string, factId: string, reason?: string): Promise<void>;
+    /**
+     * Clear all facts for a user (use with caution!)
+     */
+    clearFacts(userId: string): Promise<void>;
+    /**
+     * Start a new session for a user
+     */
+    startSession(userId: string): Promise<Session>;
+    /**
+     * End the current session for a user
+     */
+    endSession(userId: string, summary?: string): Promise<Session | null>;
+    /**
+     * Get or create a session ID for a user
+     */
+    private getOrCreateSession;
+    /**
+     * Ensure a session exists (async version)
+     */
+    private ensureSession;
+    /**
+     * Get conversation history for a user
+     */
+    getHistory(userId: string, limit?: number, sessionId?: string): Promise<ConversationExchange[]>;
+    /**
+     * Export all data for a user (for portability)
+     */
+    exportUser(userId: string): Promise<{
+        facts: MemoryFact[];
+        conversations: ConversationExchange[];
+        sessions: Session[];
+    }>;
+    /**
+     * Wait for all pending extractions to complete
+     */
+    drain(): Promise<void>;
+    /**
+     * Get the number of pending extraction tasks
+     */
+    getPendingExtractions(): number;
+    /**
+     * Close the memory system (disconnects from storage)
+     */
+    close(): Promise<void>;
+}
+
+/**
+ * Express/Connect-style request object
+ */
+interface MiddlewareRequest {
+    body?: {
+        userId?: string;
+        message?: string;
+        [key: string]: unknown;
+    };
+    params?: Record<string, string>;
+    query?: Record<string, string>;
+    headers?: Record<string, string | string[] | undefined>;
+    user?: {
+        id?: string;
+        userId?: string;
+        [key: string]: unknown;
+    };
+    memoryContext?: HydratedContext;
+}
+/**
+ * Express/Connect-style response object
+ */
+interface MiddlewareResponse {
+    locals?: Record<string, unknown>;
+    json?: (body: unknown) => void;
+    on?: (event: string, callback: () => void) => void;
+}
+/**
+ * Next function to call the next middleware
+ */
+type NextFunction = (error?: unknown) => void;
+/**
+ * Options for the memory middleware
+ */
+interface MemoryMiddlewareOptions {
+    /** Function to extract userId from request */
+    getUserId?: (req: MiddlewareRequest) => string | undefined;
+    /** Function to extract user message from request */
+    getMessage?: (req: MiddlewareRequest) => string | undefined;
+    /** Attach context to request object */
+    attachToRequest?: boolean;
+    /** Auto-digest on response finish (requires response body capture) */
+    autoDigest?: boolean;
+}
+/**
+ * Result attached to request/response
+ */
+declare global {
+    namespace Express {
+        interface Request {
+            memoryContext?: HydratedContext;
+        }
+        interface Locals {
+            memoryContext?: HydratedContext;
+        }
+    }
+}
+/**
+ * Create Express middleware for automatic context hydration.
+ *
+ * @example
+ * ```typescript
+ * import express from 'express';
+ * import { MemoryOS } from 'mem-ts';
+ * import { createMemoryMiddleware } from 'mem-ts/middleware';
+ *
+ * const app = express();
+ * const memory = new MemoryOS({ ... });
+ *
+ * app.use('/chat', createMemoryMiddleware(memory, {
+ *   getUserId: (req) => req.user?.id,
+ *   getMessage: (req) => req.body?.message,
+ * }));
+ *
+ * app.post('/chat', (req, res) => {
+ *   const context = req.memoryContext;
+ *   // Use context.compiledPrompt in your LLM call
+ * });
+ * ```
+ */
+declare function createMemoryMiddleware(memory: MemoryOS, options?: MemoryMiddlewareOptions): (req: MiddlewareRequest, res: MiddlewareResponse, next: NextFunction) => Promise<void>;
+/**
+ * Helper function to digest after response in Express.
+ * Call this after sending the response.
+ *
+ * @example
+ * ```typescript
+ * app.post('/chat', async (req, res) => {
+ *   const response = await callLLM(req.memoryContext, req.body.message);
+ *   res.json({ message: response });
+ *
+ *   // Digest in background
+ *   digestAfterResponse(memory, req.user.id, req.body.message, response);
+ * });
+ * ```
+ */
+declare function digestAfterResponse(memory: MemoryOS, userId: string, userMessage: string, assistantResponse: string): void;
+/**
+ * Create a Next.js API route handler wrapper.
+ *
+ * @example
+ * ```typescript
+ * // pages/api/chat.ts or app/api/chat/route.ts
+ * import { withMemory } from 'mem-ts/middleware';
+ *
+ * export const POST = withMemory(memory, async (req, context) => {
+ *   const { message } = await req.json();
+ *   const response = await callLLM(context.compiledPrompt, message);
+ *   return Response.json({ message: response });
+ * }, {
+ *   getUserId: (req) => req.headers.get('x-user-id'),
+ * });
+ * ```
+ */
+declare function withMemory<T extends {
+    json: () => Promise<{
+        message?: string;
+        userId?: string;
+    }>;
+}>(memory: MemoryOS, handler: (req: T, context: HydratedContext) => Promise<Response>, options?: {
+    getUserId?: (req: T) => string | null | undefined;
+    getMessage?: (body: {
+        message?: string;
+    }) => string | undefined;
+}): (req: T) => Promise<Response>;
+
+export { MemoryOS as M, type NextFunction as N, type MemoryOSConfig as a, type MemoryMiddlewareOptions as b, createMemoryMiddleware as c, digestAfterResponse as d, type MiddlewareRequest as e, type MiddlewareResponse as f, withMemory as w };