remembra 0.7.0

package/README.md

@@ -0,0 +1,179 @@
+# Remembra TypeScript SDK
+
+TypeScript/JavaScript SDK for [Remembra](https://remembra.dev) - the AI Memory Layer.
+
+## Installation
+
+```bash
+npm install remembra
+# or
+yarn add remembra
+# or
+pnpm add remembra
+```
+
+## Quick Start
+
+```typescript
+import { Remembra } from 'remembra';
+
+// Initialize client
+const memory = new Remembra({
+  url: 'http://localhost:8787',  // Self-hosted
+  apiKey: 'your-api-key',        // Optional for self-hosted
+  userId: 'user_123',
+});
+
+// Store a memory
+const stored = await memory.store('User prefers dark mode and hates long emails');
+console.log(stored.extracted_facts);
+// ['User prefers dark mode', 'User hates long emails']
+
+// Recall memories
+const result = await memory.recall('What are user preferences?');
+console.log(result.context);
+// 'User prefers dark mode. User hates long emails.'
+```
+
+## Conversation Ingestion
+
+Automatically extract memories from conversations:
+
+```typescript
+const result = await memory.ingestConversation([
+  { role: 'user', content: 'My wife Suzan and I are planning a trip to Japan' },
+  { role: 'assistant', content: 'That sounds exciting! When are you going?' },
+  { role: 'user', content: 'We are thinking April next year' },
+], {
+  minImportance: 0.5,
+});
+
+console.log(`Extracted: ${result.stats.facts_extracted} facts`);
+console.log(`Stored: ${result.stats.facts_stored} memories`);
+
+// Facts extracted:
+// - "User's wife is named Suzan"
+// - "User is planning a trip to Japan in April"
+```
+
+## API Reference
+
+### Constructor
+
+```typescript
+new Remembra(config: RemembraConfig)
+```
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `url` | string | `http://localhost:8787` | Remembra server URL |
+| `apiKey` | string | - | API key for authentication |
+| `userId` | string | **required** | User ID for memory isolation |
+| `project` | string | `default` | Project namespace |
+| `timeout` | number | `30000` | Request timeout (ms) |
+| `debug` | boolean | `false` | Enable debug logging |
+
+### Methods
+
+#### `store(content, options?)`
+
+Store a new memory.
+
+```typescript
+const result = await memory.store('John is the CEO of Acme Corp', {
+  metadata: { source: 'meeting' },
+  ttl: '30d',  // Expires in 30 days
+});
+```
+
+#### `recall(query, options?)`
+
+Recall relevant memories.
+
+```typescript
+const result = await memory.recall('Who is John?', {
+  limit: 10,
+  threshold: 0.5,
+});
+
+console.log(result.context);   // Synthesized context
+console.log(result.memories);  // Individual memories
+console.log(result.entities);  // Related entities
+```
+
+#### `ingestConversation(messages, options?)`
+
+Ingest a conversation and extract memories.
+
+```typescript
+const result = await memory.ingestConversation(messages, {
+  sessionId: 'session_123',
+  extractFrom: 'both',    // 'user' | 'assistant' | 'both'
+  minImportance: 0.5,
+  dedupe: true,
+  store: true,            // false for dry-run
+  infer: true,            // false to store raw messages
+});
+```
+
+#### `forget(options)`
+
+Delete memories (GDPR-compliant).
+
+```typescript
+// Delete specific memory
+await memory.forget({ memoryId: 'mem_123' });
+
+// Delete all about an entity
+await memory.forget({ entity: 'John' });
+
+// Delete all user memories
+await memory.forget();
+```
+
+#### `get(memoryId)`
+
+Get a specific memory by ID.
+
+```typescript
+const mem = await memory.get('mem_123');
+```
+
+#### `health()`
+
+Check server health.
+
+```typescript
+const health = await memory.health();
+```
+
+## Error Handling
+
+```typescript
+import { 
+  RemembraError,
+  AuthenticationError,
+  RateLimitError,
+  ValidationError,
+} from 'remembra';
+
+try {
+  await memory.store(content);
+} catch (error) {
+  if (error instanceof AuthenticationError) {
+    // Handle auth error
+  } else if (error instanceof RateLimitError) {
+    // Wait and retry
+    console.log(`Retry after ${error.retryAfter} seconds`);
+  } else if (error instanceof ValidationError) {
+    // Handle validation error
+  } else if (error instanceof RemembraError) {
+    // Generic Remembra error
+    console.log(error.status, error.message);
+  }
+}
+```
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -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 };