remembra 0.7.0

package/dist/index.d.ts

@@ -0,0 +1,295 @@
+/**
+ * Remembra TypeScript SDK Types
+ */
+interface RemembraConfig {
+    /** Remembra server URL */
+    url?: string;
+    /** API key for authentication */
+    apiKey?: string;
+    /** User ID for memory operations */
+    userId: string;
+    /** Project namespace */
+    project?: string;
+    /** Request timeout in milliseconds */
+    timeout?: number;
+    /** Enable debug logging */
+    debug?: boolean;
+}
+interface EntityRef {
+    id: string;
+    canonical_name: string;
+    type: string;
+    confidence: number;
+}
+interface Memory {
+    id: string;
+    content: string;
+    relevance: number;
+    created_at: string;
+    metadata?: Record<string, unknown>;
+}
+interface StoreOptions {
+    /** Optional key-value metadata */
+    metadata?: Record<string, unknown>;
+    /** Time-to-live (e.g., "30d", "1y") */
+    ttl?: string;
+}
+interface StoreResult {
+    id: string;
+    extracted_facts: string[];
+    entities: EntityRef[];
+}
+interface RecallOptions {
+    /** Maximum results (1-50) */
+    limit?: number;
+    /** Minimum relevance threshold (0.0-1.0) */
+    threshold?: number;
+    /** Maximum tokens in context */
+    maxTokens?: number;
+    /** Enable hybrid search */
+    enableHybrid?: boolean;
+    /** Enable reranking */
+    enableRerank?: boolean;
+}
+interface RecallResult {
+    context: string;
+    memories: Memory[];
+    entities: EntityRef[];
+}
+interface ForgetOptions {
+    /** Delete specific memory by ID */
+    memoryId?: string;
+    /** Delete all memories about an entity */
+    entity?: string;
+}
+interface ForgetResult {
+    deleted_memories: number;
+    deleted_entities: number;
+    deleted_relationships: number;
+}
+interface Message {
+    /** Message role: user, assistant, or system */
+    role: 'user' | 'assistant' | 'system';
+    /** Message content */
+    content: string;
+    /** Optional speaker name */
+    name?: string;
+    /** Optional timestamp (ISO format) */
+    timestamp?: string;
+    /** Optional metadata */
+    metadata?: Record<string, unknown>;
+}
+interface IngestOptions {
+    /** Session ID for grouping conversations */
+    sessionId?: string;
+    /** Which messages to extract from */
+    extractFrom?: 'user' | 'assistant' | 'both';
+    /** Minimum importance threshold (0.0-1.0) */
+    minImportance?: number;
+    /** Enable deduplication */
+    dedupe?: boolean;
+    /** Store results (false for dry-run) */
+    store?: boolean;
+    /** Enable extraction (false to store raw) */
+    infer?: boolean;
+}
+interface ExtractedFact {
+    content: string;
+    confidence: number;
+    importance: number;
+    source_message_index: number;
+    speaker: string | null;
+    stored: boolean;
+    memory_id: string | null;
+    action: 'add' | 'update' | 'delete' | 'noop' | 'skipped';
+    action_reason: string | null;
+}
+interface ExtractedEntity {
+    name: string;
+    type: string;
+    relationship: string | null;
+}
+interface IngestStats {
+    messages_processed: number;
+    facts_extracted: number;
+    facts_stored: number;
+    facts_updated: number;
+    facts_deduped: number;
+    facts_skipped: number;
+    entities_found: number;
+    processing_time_ms: number;
+}
+interface IngestResult {
+    status: 'ok' | 'partial' | 'error';
+    session_id: string | null;
+    facts: ExtractedFact[];
+    entities: ExtractedEntity[];
+    stats: IngestStats;
+}
+
+/**
+ * Remembra TypeScript Client
+ *
+ * Main interface for the Remembra AI Memory Layer.
+ *
+ * @example
+ * ```typescript
+ * import { Remembra } from 'remembra';
+ *
+ * const memory = new Remembra({
+ *   url: 'http://localhost:8787',
+ *   apiKey: 'your-api-key',
+ *   userId: 'user_123',
+ * });
+ *
+ * // Store a memory
+ * const stored = await memory.store('User prefers dark mode');
+ *
+ * // Recall memories
+ * const result = await memory.recall('What are user preferences?');
+ * console.log(result.context);
+ *
+ * // Ingest a conversation
+ * const ingestResult = await memory.ingestConversation([
+ *   { role: 'user', content: 'My name is John' },
+ *   { role: 'assistant', content: 'Nice to meet you, John!' },
+ * ]);
+ * ```
+ */
+
+declare class Remembra {
+    private readonly url;
+    private readonly apiKey?;
+    private readonly userId;
+    private readonly project;
+    private readonly timeout;
+    private readonly debug;
+    constructor(config: RemembraConfig);
+    private log;
+    private request;
+    private sleep;
+    /**
+     * Store a new memory.
+     *
+     * @param content - Text content to memorize
+     * @param options - Optional metadata and TTL
+     * @returns Stored memory with extracted facts and entities
+     *
+     * @example
+     * ```typescript
+     * const result = await memory.store('User prefers dark mode', {
+     *   metadata: { source: 'settings' },
+     *   ttl: '30d',
+     * });
+     * console.log(result.extracted_facts);
+     * ```
+     */
+    store(content: string, options?: StoreOptions): Promise<StoreResult>;
+    /**
+     * Recall memories relevant to a query.
+     *
+     * @param query - Natural language query
+     * @param options - Recall options (limit, threshold, etc.)
+     * @returns Context string and matching memories
+     *
+     * @example
+     * ```typescript
+     * const result = await memory.recall('What are user preferences?');
+     * console.log(result.context); // Synthesized context
+     * console.log(result.memories); // Individual memories
+     * ```
+     */
+    recall(query: string, options?: RecallOptions): Promise<RecallResult>;
+    /**
+     * Get a specific memory by ID.
+     *
+     * @param memoryId - Memory ID
+     * @returns Memory details
+     */
+    get(memoryId: string): Promise<Memory>;
+    /**
+     * Forget (delete) memories.
+     *
+     * @param options - What to delete (memoryId, entity, or all)
+     * @returns Deletion counts
+     *
+     * @example
+     * ```typescript
+     * // Delete specific memory
+     * await memory.forget({ memoryId: 'mem_123' });
+     *
+     * // Delete all about an entity
+     * await memory.forget({ entity: 'John' });
+     * ```
+     */
+    forget(options?: ForgetOptions): Promise<ForgetResult>;
+    /**
+     * Ingest a conversation and automatically extract memories.
+     *
+     * This is the primary method for AI agents to add conversation context
+     * to persistent memory without manually calling store for each fact.
+     *
+     * @param messages - Array of conversation messages
+     * @param options - Ingestion options
+     * @returns Extracted facts, entities, and stats
+     *
+     * @example
+     * ```typescript
+     * const result = await memory.ingestConversation([
+     *   { role: 'user', content: 'My name is John and I work at Google' },
+     *   { role: 'assistant', content: 'Nice to meet you, John!' },
+     * ], {
+     *   minImportance: 0.5,
+     * });
+     *
+     * console.log(`Extracted ${result.stats.facts_extracted} facts`);
+     * console.log(`Stored ${result.stats.facts_stored} new memories`);
+     * ```
+     */
+    ingestConversation(messages: Message[], options?: IngestOptions): Promise<IngestResult>;
+    /**
+     * Check server health.
+     *
+     * @returns Health status
+     */
+    health(): Promise<Record<string, unknown>>;
+    /**
+     * List entities for the current user.
+     *
+     * @returns Array of entities
+     */
+    listEntities(): Promise<EntityRef[]>;
+}
+
+/**
+ * Remembra SDK Error Classes
+ */
+declare class RemembraError extends Error {
+    readonly status?: number;
+    readonly code?: string;
+    constructor(message: string, status?: number, code?: string);
+}
+declare class AuthenticationError extends RemembraError {
+    constructor(message?: string);
+}
+declare class NotFoundError extends RemembraError {
+    constructor(message?: string);
+}
+declare class ValidationError extends RemembraError {
+    constructor(message: string);
+}
+declare class RateLimitError extends RemembraError {
+    readonly retryAfter?: number;
+    constructor(message?: string, retryAfter?: number);
+}
+declare class ServerError extends RemembraError {
+    constructor(message?: string);
+}
+declare class NetworkError extends RemembraError {
+    constructor(message?: string);
+}
+declare class TimeoutError extends RemembraError {
+    constructor(message?: string);
+}
+
+export { AuthenticationError, type EntityRef, type ExtractedEntity, type ExtractedFact, type ForgetOptions, type ForgetResult, type IngestOptions, type IngestResult, type IngestStats, type Memory, type Message, NetworkError, NotFoundError, RateLimitError, type RecallOptions, type RecallResult, Remembra, type RemembraConfig, RemembraError, ServerError, type StoreOptions, type StoreResult, TimeoutError, ValidationError };

package/dist/index.js

@@ -0,0 +1,375 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  AuthenticationError: () => AuthenticationError,
+  NetworkError: () => NetworkError,
+  NotFoundError: () => NotFoundError,
+  RateLimitError: () => RateLimitError,
+  Remembra: () => Remembra,
+  RemembraError: () => RemembraError,
+  ServerError: () => ServerError,
+  TimeoutError: () => TimeoutError,
+  ValidationError: () => ValidationError
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/errors.ts
+var RemembraError = class _RemembraError extends Error {
+  constructor(message, status, code) {
+    super(message);
+    this.name = "RemembraError";
+    this.status = status;
+    this.code = code;
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, _RemembraError);
+    }
+  }
+};
+var AuthenticationError = class extends RemembraError {
+  constructor(message = "Authentication failed") {
+    super(message, 401, "AUTH_ERROR");
+    this.name = "AuthenticationError";
+  }
+};
+var NotFoundError = class extends RemembraError {
+  constructor(message = "Resource not found") {
+    super(message, 404, "NOT_FOUND");
+    this.name = "NotFoundError";
+  }
+};
+var ValidationError = class extends RemembraError {
+  constructor(message) {
+    super(message, 422, "VALIDATION_ERROR");
+    this.name = "ValidationError";
+  }
+};
+var RateLimitError = class extends RemembraError {
+  constructor(message = "Rate limit exceeded", retryAfter) {
+    super(message, 429, "RATE_LIMITED");
+    this.name = "RateLimitError";
+    this.retryAfter = retryAfter;
+  }
+};
+var ServerError = class extends RemembraError {
+  constructor(message = "Internal server error") {
+    super(message, 500, "SERVER_ERROR");
+    this.name = "ServerError";
+  }
+};
+var NetworkError = class extends RemembraError {
+  constructor(message = "Network error") {
+    super(message, void 0, "NETWORK_ERROR");
+    this.name = "NetworkError";
+  }
+};
+var TimeoutError = class extends RemembraError {
+  constructor(message = "Request timed out") {
+    super(message, void 0, "TIMEOUT");
+    this.name = "TimeoutError";
+  }
+};
+
+// src/client.ts
+var DEFAULT_URL = "http://localhost:8787";
+var DEFAULT_TIMEOUT = 3e4;
+var MAX_RETRIES = 3;
+var RETRY_DELAY = 1e3;
+var Remembra = class {
+  constructor(config) {
+    this.url = (config.url || DEFAULT_URL).replace(/\/$/, "");
+    this.apiKey = config.apiKey;
+    this.userId = config.userId;
+    this.project = config.project || "default";
+    this.timeout = config.timeout || DEFAULT_TIMEOUT;
+    this.debug = config.debug || false;
+    if (!this.userId) {
+      throw new ValidationError("userId is required");
+    }
+  }
+  // ===========================================================================
+  // Private Methods
+  // ===========================================================================
+  log(...args) {
+    if (this.debug) {
+      console.log("[Remembra]", ...args);
+    }
+  }
+  async request(method, path, options = {}) {
+    const { body, params, retries = MAX_RETRIES } = options;
+    const url = new URL(`${this.url}${path}`);
+    if (params) {
+      Object.entries(params).forEach(([key, value]) => {
+        if (value !== void 0) {
+          url.searchParams.set(key, value);
+        }
+      });
+    }
+    const headers = {
+      "Content-Type": "application/json",
+      "User-Agent": "remembra-js/0.1.0"
+    };
+    if (this.apiKey) {
+      headers["X-API-Key"] = this.apiKey;
+    }
+    this.log(method, path, body ? JSON.stringify(body).slice(0, 100) : "");
+    let lastError;
+    for (let attempt = 0; attempt < retries; attempt++) {
+      try {
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+        const response = await fetch(url.toString(), {
+          method,
+          headers,
+          body: body ? JSON.stringify(body) : void 0,
+          signal: controller.signal
+        });
+        clearTimeout(timeoutId);
+        if (response.ok) {
+          return await response.json();
+        }
+        const errorBody = await response.json().catch(() => ({}));
+        const errorMessage = errorBody.detail || response.statusText;
+        switch (response.status) {
+          case 401:
+            throw new AuthenticationError(errorMessage);
+          case 404:
+            throw new NotFoundError(errorMessage);
+          case 422:
+            throw new ValidationError(errorMessage);
+          case 429:
+            const retryAfter = parseInt(response.headers.get("Retry-After") || "60", 10);
+            if (attempt < retries - 1) {
+              this.log(`Rate limited, retrying in ${retryAfter}s...`);
+              await this.sleep(retryAfter * 1e3);
+              continue;
+            }
+            throw new RateLimitError(errorMessage, retryAfter);
+          case 500:
+          case 502:
+          case 503:
+          case 504:
+            if (attempt < retries - 1) {
+              this.log(`Server error (${response.status}), retrying...`);
+              await this.sleep(RETRY_DELAY * Math.pow(2, attempt));
+              continue;
+            }
+            throw new ServerError(errorMessage);
+          default:
+            throw new RemembraError(errorMessage, response.status);
+        }
+      } catch (error) {
+        lastError = error;
+        if (error instanceof RemembraError) {
+          throw error;
+        }
+        if (error instanceof Error) {
+          if (error.name === "AbortError") {
+            throw new TimeoutError(`Request timed out after ${this.timeout}ms`);
+          }
+          if (attempt < retries - 1) {
+            this.log(`Network error, retrying...`, error.message);
+            await this.sleep(RETRY_DELAY * Math.pow(2, attempt));
+            continue;
+          }
+          throw new NetworkError(error.message);
+        }
+      }
+    }
+    throw lastError || new NetworkError("Request failed");
+  }
+  sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+  // ===========================================================================
+  // Core Operations
+  // ===========================================================================
+  /**
+   * Store a new memory.
+   * 
+   * @param content - Text content to memorize
+   * @param options - Optional metadata and TTL
+   * @returns Stored memory with extracted facts and entities
+   * 
+   * @example
+   * ```typescript
+   * const result = await memory.store('User prefers dark mode', {
+   *   metadata: { source: 'settings' },
+   *   ttl: '30d',
+   * });
+   * console.log(result.extracted_facts);
+   * ```
+   */
+  async store(content, options = {}) {
+    return this.request("POST", "/api/v1/memories", {
+      body: {
+        user_id: this.userId,
+        project_id: this.project,
+        content,
+        metadata: options.metadata || {},
+        ttl: options.ttl
+      }
+    });
+  }
+  /**
+   * Recall memories relevant to a query.
+   * 
+   * @param query - Natural language query
+   * @param options - Recall options (limit, threshold, etc.)
+   * @returns Context string and matching memories
+   * 
+   * @example
+   * ```typescript
+   * const result = await memory.recall('What are user preferences?');
+   * console.log(result.context); // Synthesized context
+   * console.log(result.memories); // Individual memories
+   * ```
+   */
+  async recall(query, options = {}) {
+    return this.request("POST", "/api/v1/memories/recall", {
+      body: {
+        user_id: this.userId,
+        project_id: this.project,
+        query,
+        limit: options.limit || 5,
+        threshold: options.threshold || 0.4,
+        max_tokens: options.maxTokens,
+        enable_hybrid: options.enableHybrid,
+        enable_rerank: options.enableRerank
+      }
+    });
+  }
+  /**
+   * Get a specific memory by ID.
+   * 
+   * @param memoryId - Memory ID
+   * @returns Memory details
+   */
+  async get(memoryId) {
+    return this.request("GET", `/api/v1/memories/${memoryId}`);
+  }
+  /**
+   * Forget (delete) memories.
+   * 
+   * @param options - What to delete (memoryId, entity, or all)
+   * @returns Deletion counts
+   * 
+   * @example
+   * ```typescript
+   * // Delete specific memory
+   * await memory.forget({ memoryId: 'mem_123' });
+   * 
+   * // Delete all about an entity
+   * await memory.forget({ entity: 'John' });
+   * ```
+   */
+  async forget(options = {}) {
+    const params = {};
+    if (options.memoryId) {
+      params.memory_id = options.memoryId;
+    } else if (options.entity) {
+      params.entity = options.entity;
+    } else {
+      params.user_id = this.userId;
+    }
+    return this.request("DELETE", "/api/v1/memories", { params });
+  }
+  // ===========================================================================
+  // Conversation Ingestion
+  // ===========================================================================
+  /**
+   * Ingest a conversation and automatically extract memories.
+   * 
+   * This is the primary method for AI agents to add conversation context
+   * to persistent memory without manually calling store for each fact.
+   * 
+   * @param messages - Array of conversation messages
+   * @param options - Ingestion options
+   * @returns Extracted facts, entities, and stats
+   * 
+   * @example
+   * ```typescript
+   * const result = await memory.ingestConversation([
+   *   { role: 'user', content: 'My name is John and I work at Google' },
+   *   { role: 'assistant', content: 'Nice to meet you, John!' },
+   * ], {
+   *   minImportance: 0.5,
+   * });
+   * 
+   * console.log(`Extracted ${result.stats.facts_extracted} facts`);
+   * console.log(`Stored ${result.stats.facts_stored} new memories`);
+   * ```
+   */
+  async ingestConversation(messages, options = {}) {
+    return this.request("POST", "/api/v1/ingest/conversation", {
+      body: {
+        messages,
+        user_id: this.userId,
+        project_id: this.project,
+        session_id: options.sessionId,
+        options: {
+          extract_from: options.extractFrom || "both",
+          min_importance: options.minImportance ?? 0.5,
+          dedupe: options.dedupe ?? true,
+          store: options.store ?? true,
+          infer: options.infer ?? true
+        }
+      }
+    });
+  }
+  // ===========================================================================
+  // Utilities
+  // ===========================================================================
+  /**
+   * Check server health.
+   * 
+   * @returns Health status
+   */
+  async health() {
+    return this.request("GET", "/health");
+  }
+  /**
+   * List entities for the current user.
+   * 
+   * @returns Array of entities
+   */
+  async listEntities() {
+    const result = await this.request(
+      "GET",
+      "/api/v1/entities",
+      { params: { user_id: this.userId, project_id: this.project } }
+    );
+    return result.entities || [];
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AuthenticationError,
+  NetworkError,
+  NotFoundError,
+  RateLimitError,
+  Remembra,
+  RemembraError,
+  ServerError,
+  TimeoutError,
+  ValidationError
+});
+//# sourceMappingURL=index.js.map