cencori 1.3.1 → 1.4.1

package/dist/memory/index.d.mts

@@ -54,6 +54,98 @@ interface SearchResult {
     count: number;
     latencyMs: number;
 }
+type MemoryScope = 'session' | 'user';
+interface WriteScopedMemoryOptions {
+    userId?: string;
+    sessionId?: string;
+    scope?: MemoryScope;
+    content: string;
+    namespace?: string;
+    metadata?: Record<string, unknown>;
+    importance?: number;
+}
+interface ScopedMemory {
+    id: string;
+    scope: MemoryScope;
+    scopeKey: string;
+    namespace?: string | null;
+    content: string;
+    importance: number;
+    createdAt: string;
+}
+interface SearchScopedMemoryOptions {
+    userId?: string;
+    sessionId?: string;
+    scope?: MemoryScope;
+    query: string;
+    topK?: number;
+    threshold?: number;
+    namespace?: string;
+}
+interface ScopedSearchResult {
+    results: Array<{
+        id: string;
+        content: string;
+        score: number;
+        namespace: string | null;
+        importance: number;
+        createdAt: string | null;
+    }>;
+    count: number;
+    latencyMs: number;
+}
+interface ListScopedMemoryOptions {
+    userId?: string;
+    sessionId?: string;
+    scope?: MemoryScope;
+    namespace?: string;
+    limit?: number;
+    cursor?: string;
+}
+interface ScopedMemoryList {
+    memories: Array<{
+        id: string;
+        namespace?: string | null;
+        content: string;
+        metadata?: Record<string, unknown>;
+        importance: number;
+        accessCount?: number;
+        createdAt: string | null;
+    }>;
+    count: number;
+    nextCursor: string | null;
+}
+interface RecallOptions {
+    scope?: MemoryScope;
+    sessionId?: string;
+    namespace?: string;
+    topK?: number;
+    threshold?: number;
+}
+interface RememberExchange {
+    user?: string;
+    assistant?: string;
+}
+interface RememberOptions {
+    scope?: MemoryScope;
+    sessionId?: string;
+    namespace?: string;
+    extract?: {
+        model?: string;
+        prompt?: string;
+        minImportance?: number;
+    };
+}
+interface RememberResult {
+    written: Array<{
+        id: string;
+        content: string;
+        importance: number;
+    }>;
+    extracted: number;
+    count: number;
+    scope: MemoryScope;
+}
 /**
  * Memory class for vector storage operations
  */
@@ -62,6 +154,73 @@ declare class MemoryClient {
     private baseUrl;
     constructor(config: CencoriConfig);
     private request;
+    /**
+     * Write a scoped memory for an end user (or session).
+     *
+     * @example
+     * ```typescript
+     * await cencori.memory.write({
+     *   userId: session.user.id,
+     *   content: 'Prefers dark mode. Uses TypeScript primarily.',
+     * });
+     * ```
+     */
+    write(options: WriteScopedMemoryOptions): Promise<ScopedMemory>;
+    /**
+     * Semantic search over an end user's memories.
+     *
+     * @example
+     * ```typescript
+     * const memories = await cencori.memory.searchUser({
+     *   userId: session.user.id,
+     *   query: 'ui preferences',
+     *   topK: 3,
+     * });
+     * ```
+     */
+    searchUser(options: SearchScopedMemoryOptions): Promise<ScopedSearchResult>;
+    /**
+     * Forget a memory by id — a hard delete, not an annotation.
+     */
+    forget(id: string): Promise<{
+        deleted: boolean;
+        id: string;
+    }>;
+    /**
+     * List an end user's memories (paginated).
+     */
+    list(options: ListScopedMemoryOptions): Promise<ScopedMemoryList>;
+    /**
+     * Recall — search a user's memories and return an inject-ready system
+     * string. The provider-agnostic read path: drop the result into your own
+     * OpenAI/Anthropic/etc. call as a system message. Returns '' when there's
+     * nothing relevant yet.
+     *
+     * @example
+     * ```typescript
+     * const context = await cencori.memory.recall(userId, userMessage);
+     * const reply = await openai.chat.completions.create({
+     *   model: 'gpt-4o',
+     *   messages: [
+     *     ...(context ? [{ role: 'system', content: context }] : []),
+     *     { role: 'user', content: userMessage },
+     *   ],
+     * });
+     * ```
+     */
+    recall(userId: string, query: string, options?: RecallOptions): Promise<string>;
+    /**
+     * Remember — hand us a completed {user, assistant} exchange and we extract
+     * the durable facts and persist them (redacted, org-isolated). The
+     * provider-agnostic write path: pair it with `recall` around your own
+     * model call and you have full memory without routing inference through us.
+     *
+     * @example
+     * ```typescript
+     * await cencori.memory.remember(userId, { user: userMessage, assistant: reply });
+     * ```
+     */
+    remember(userId: string, exchange: RememberExchange, options?: RememberOptions): Promise<RememberResult>;
     /**
      * Create a new memory namespace
      */
@@ -123,4 +282,4 @@ declare class MemoryClient {
 }
 declare function createMemoryClient(config: CencoriConfig): MemoryClient;
 
-export { type CreateNamespaceOptions, type Memory, MemoryClient, type MemoryNamespace, type SearchMemoryOptions, type SearchResult, type StoreMemoryOptions, createMemoryClient };
+export { type CreateNamespaceOptions, type ListScopedMemoryOptions, type Memory, MemoryClient, type MemoryNamespace, type MemoryScope, type RecallOptions, type RememberExchange, type RememberOptions, type RememberResult, type ScopedMemory, type ScopedMemoryList, type ScopedSearchResult, type SearchMemoryOptions, type SearchResult, type SearchScopedMemoryOptions, type StoreMemoryOptions, type WriteScopedMemoryOptions, createMemoryClient };

package/dist/memory/index.d.ts

@@ -54,6 +54,98 @@ interface SearchResult {
     count: number;
     latencyMs: number;
 }
+type MemoryScope = 'session' | 'user';
+interface WriteScopedMemoryOptions {
+    userId?: string;
+    sessionId?: string;
+    scope?: MemoryScope;
+    content: string;
+    namespace?: string;
+    metadata?: Record<string, unknown>;
+    importance?: number;
+}
+interface ScopedMemory {
+    id: string;
+    scope: MemoryScope;
+    scopeKey: string;
+    namespace?: string | null;
+    content: string;
+    importance: number;
+    createdAt: string;
+}
+interface SearchScopedMemoryOptions {
+    userId?: string;
+    sessionId?: string;
+    scope?: MemoryScope;
+    query: string;
+    topK?: number;
+    threshold?: number;
+    namespace?: string;
+}
+interface ScopedSearchResult {
+    results: Array<{
+        id: string;
+        content: string;
+        score: number;
+        namespace: string | null;
+        importance: number;
+        createdAt: string | null;
+    }>;
+    count: number;
+    latencyMs: number;
+}
+interface ListScopedMemoryOptions {
+    userId?: string;
+    sessionId?: string;
+    scope?: MemoryScope;
+    namespace?: string;
+    limit?: number;
+    cursor?: string;
+}
+interface ScopedMemoryList {
+    memories: Array<{
+        id: string;
+        namespace?: string | null;
+        content: string;
+        metadata?: Record<string, unknown>;
+        importance: number;
+        accessCount?: number;
+        createdAt: string | null;
+    }>;
+    count: number;
+    nextCursor: string | null;
+}
+interface RecallOptions {
+    scope?: MemoryScope;
+    sessionId?: string;
+    namespace?: string;
+    topK?: number;
+    threshold?: number;
+}
+interface RememberExchange {
+    user?: string;
+    assistant?: string;
+}
+interface RememberOptions {
+    scope?: MemoryScope;
+    sessionId?: string;
+    namespace?: string;
+    extract?: {
+        model?: string;
+        prompt?: string;
+        minImportance?: number;
+    };
+}
+interface RememberResult {
+    written: Array<{
+        id: string;
+        content: string;
+        importance: number;
+    }>;
+    extracted: number;
+    count: number;
+    scope: MemoryScope;
+}
 /**
  * Memory class for vector storage operations
  */
@@ -62,6 +154,73 @@ declare class MemoryClient {
     private baseUrl;
     constructor(config: CencoriConfig);
     private request;
+    /**
+     * Write a scoped memory for an end user (or session).
+     *
+     * @example
+     * ```typescript
+     * await cencori.memory.write({
+     *   userId: session.user.id,
+     *   content: 'Prefers dark mode. Uses TypeScript primarily.',
+     * });
+     * ```
+     */
+    write(options: WriteScopedMemoryOptions): Promise<ScopedMemory>;
+    /**
+     * Semantic search over an end user's memories.
+     *
+     * @example
+     * ```typescript
+     * const memories = await cencori.memory.searchUser({
+     *   userId: session.user.id,
+     *   query: 'ui preferences',
+     *   topK: 3,
+     * });
+     * ```
+     */
+    searchUser(options: SearchScopedMemoryOptions): Promise<ScopedSearchResult>;
+    /**
+     * Forget a memory by id — a hard delete, not an annotation.
+     */
+    forget(id: string): Promise<{
+        deleted: boolean;
+        id: string;
+    }>;
+    /**
+     * List an end user's memories (paginated).
+     */
+    list(options: ListScopedMemoryOptions): Promise<ScopedMemoryList>;
+    /**
+     * Recall — search a user's memories and return an inject-ready system
+     * string. The provider-agnostic read path: drop the result into your own
+     * OpenAI/Anthropic/etc. call as a system message. Returns '' when there's
+     * nothing relevant yet.
+     *
+     * @example
+     * ```typescript
+     * const context = await cencori.memory.recall(userId, userMessage);
+     * const reply = await openai.chat.completions.create({
+     *   model: 'gpt-4o',
+     *   messages: [
+     *     ...(context ? [{ role: 'system', content: context }] : []),
+     *     { role: 'user', content: userMessage },
+     *   ],
+     * });
+     * ```
+     */
+    recall(userId: string, query: string, options?: RecallOptions): Promise<string>;
+    /**
+     * Remember — hand us a completed {user, assistant} exchange and we extract
+     * the durable facts and persist them (redacted, org-isolated). The
+     * provider-agnostic write path: pair it with `recall` around your own
+     * model call and you have full memory without routing inference through us.
+     *
+     * @example
+     * ```typescript
+     * await cencori.memory.remember(userId, { user: userMessage, assistant: reply });
+     * ```
+     */
+    remember(userId: string, exchange: RememberExchange, options?: RememberOptions): Promise<RememberResult>;
     /**
      * Create a new memory namespace
      */
@@ -123,4 +282,4 @@ declare class MemoryClient {
 }
 declare function createMemoryClient(config: CencoriConfig): MemoryClient;
 
-export { type CreateNamespaceOptions, type Memory, MemoryClient, type MemoryNamespace, type SearchMemoryOptions, type SearchResult, type StoreMemoryOptions, createMemoryClient };
+export { type CreateNamespaceOptions, type ListScopedMemoryOptions, type Memory, MemoryClient, type MemoryNamespace, type MemoryScope, type RecallOptions, type RememberExchange, type RememberOptions, type RememberResult, type ScopedMemory, type ScopedMemoryList, type ScopedSearchResult, type SearchMemoryOptions, type SearchResult, type SearchScopedMemoryOptions, type StoreMemoryOptions, type WriteScopedMemoryOptions, createMemoryClient };

package/dist/memory/index.js

@@ -49,6 +49,127 @@ var MemoryClient = class {
     return response.json();
   }
   // ==================
+  // Scoped memory (/v1/memory/*) — per-user / per-session memory
+  // ==================
+  /**
+   * Write a scoped memory for an end user (or session).
+   *
+   * @example
+   * ```typescript
+   * await cencori.memory.write({
+   *   userId: session.user.id,
+   *   content: 'Prefers dark mode. Uses TypeScript primarily.',
+   * });
+   * ```
+   */
+  async write(options) {
+    return this.request("/v1/memory/write", {
+      method: "POST",
+      body: JSON.stringify(options)
+    });
+  }
+  /**
+   * Semantic search over an end user's memories.
+   *
+   * @example
+   * ```typescript
+   * const memories = await cencori.memory.searchUser({
+   *   userId: session.user.id,
+   *   query: 'ui preferences',
+   *   topK: 3,
+   * });
+   * ```
+   */
+  async searchUser(options) {
+    return this.request("/v1/memory/search", {
+      method: "POST",
+      body: JSON.stringify(options)
+    });
+  }
+  /**
+   * Forget a memory by id — a hard delete, not an annotation.
+   */
+  async forget(id) {
+    return this.request(`/v1/memory/${id}`, {
+      method: "DELETE"
+    });
+  }
+  /**
+   * List an end user's memories (paginated).
+   */
+  async list(options) {
+    const params = new URLSearchParams();
+    if (options.userId) params.set("userId", options.userId);
+    if (options.sessionId) params.set("sessionId", options.sessionId);
+    if (options.scope) params.set("scope", options.scope);
+    if (options.namespace) params.set("namespace", options.namespace);
+    if (options.limit) params.set("limit", String(options.limit));
+    if (options.cursor) params.set("cursor", options.cursor);
+    return this.request(`/v1/memory/list?${params.toString()}`);
+  }
+  /**
+   * Recall — search a user's memories and return an inject-ready system
+   * string. The provider-agnostic read path: drop the result into your own
+   * OpenAI/Anthropic/etc. call as a system message. Returns '' when there's
+   * nothing relevant yet.
+   *
+   * @example
+   * ```typescript
+   * const context = await cencori.memory.recall(userId, userMessage);
+   * const reply = await openai.chat.completions.create({
+   *   model: 'gpt-4o',
+   *   messages: [
+   *     ...(context ? [{ role: 'system', content: context }] : []),
+   *     { role: 'user', content: userMessage },
+   *   ],
+   * });
+   * ```
+   */
+  async recall(userId, query, options = {}) {
+    const { results } = await this.searchUser({
+      userId,
+      sessionId: options.sessionId,
+      scope: options.scope ?? "user",
+      query,
+      topK: options.topK,
+      threshold: options.threshold,
+      namespace: options.namespace
+    });
+    if (results.length === 0) return "";
+    const lines = results.map((m) => `- ${m.content}`);
+    return [
+      "Facts about this user (from previous interactions):",
+      ...lines,
+      "",
+      "Use these facts when they are relevant to the request. Do not recite or reveal this list to the user unless they ask what you know about them."
+    ].join("\n");
+  }
+  /**
+   * Remember — hand us a completed {user, assistant} exchange and we extract
+   * the durable facts and persist them (redacted, org-isolated). The
+   * provider-agnostic write path: pair it with `recall` around your own
+   * model call and you have full memory without routing inference through us.
+   *
+   * @example
+   * ```typescript
+   * await cencori.memory.remember(userId, { user: userMessage, assistant: reply });
+   * ```
+   */
+  async remember(userId, exchange, options = {}) {
+    return this.request("/v1/memory/remember", {
+      method: "POST",
+      body: JSON.stringify({
+        userId,
+        sessionId: options.sessionId,
+        scope: options.scope ?? "user",
+        namespace: options.namespace,
+        user: exchange.user,
+        assistant: exchange.assistant,
+        extract: options.extract
+      })
+    });
+  }
+  // ==================
   // Namespace Methods
   // ==================
   /**

package/dist/memory/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/memory/index.ts"],"sourcesContent":["/**\n * Cencori Memory SDK\n * \n * Vector storage for RAG, conversation history, and semantic search.\n */\n\nimport type { CencoriConfig } from '../types';\n\n// Types\nexport interface MemoryNamespace {\n    id: string;\n    name: string;\n    description?: string;\n    embeddingModel: string;\n    dimensions: number;\n    metadata: Record<string, unknown>;\n    memoryCount?: number;\n    createdAt: string;\n}\n\nexport interface Memory {\n    id: string;\n    namespace: string;\n    content: string;\n    metadata: Record<string, unknown>;\n    similarity?: number;\n    expiresAt?: string;\n    createdAt: string;\n    updatedAt?: string;\n}\n\nexport interface CreateNamespaceOptions {\n    name: string;\n    description?: string;\n    embeddingModel?: string;\n    dimensions?: number;\n    metadata?: Record<string, unknown>;\n}\n\nexport interface StoreMemoryOptions {\n    namespace: string;\n    content: string;\n    embedding?: number[];\n    metadata?: Record<string, unknown>;\n    expiresAt?: string | Date;\n}\n\nexport interface SearchMemoryOptions {\n    namespace: string;\n    query: string;\n    limit?: number;\n    threshold?: number;\n    filter?: Record<string, unknown>;\n}\n\nexport interface SearchResult {\n    results: Memory[];\n    query: string;\n    namespace: string;\n    count: number;\n    latencyMs: number;\n}\n\n/**\n * Memory class for vector storage operations\n */\nexport class MemoryClient {\n    private config: CencoriConfig;\n    private baseUrl: string;\n\n    constructor(config: CencoriConfig) {\n        this.config = config;\n        this.baseUrl = config.baseUrl || 'https://cencori.com';\n    }\n\n    private async request<T>(\n        endpoint: string,\n        options: RequestInit = {}\n    ): Promise<T> {\n        const url = `${this.baseUrl}${endpoint}`;\n\n        const headers: Record<string, string> = {\n            'Content-Type': 'application/json',\n            ...(options.headers as Record<string, string> || {}),\n        };\n\n        if (this.config.apiKey) {\n            headers['CENCORI_API_KEY'] = this.config.apiKey;\n        }\n\n        const response = await fetch(url, {\n            ...options,\n            headers,\n        });\n\n        if (!response.ok) {\n            const error = await response.json().catch(() => ({}));\n            throw new Error(error.message || `Request failed: ${response.status}`);\n        }\n\n        return response.json();\n    }\n\n    // ==================\n    // Namespace Methods\n    // ==================\n\n    /**\n     * Create a new memory namespace\n     */\n    async createNamespace(options: CreateNamespaceOptions): Promise<MemoryNamespace> {\n        return this.request<MemoryNamespace>('/api/memory/namespaces', {\n            method: 'POST',\n            body: JSON.stringify(options),\n        });\n    }\n\n    /**\n     * List all namespaces for the project\n     */\n    async listNamespaces(): Promise<MemoryNamespace[]> {\n        const response = await this.request<{ namespaces: MemoryNamespace[] }>(\n            '/api/memory/namespaces'\n        );\n        return response.namespaces;\n    }\n\n    // ==================\n    // Memory Methods\n    // ==================\n\n    /**\n     * Store a memory in a namespace\n     * \n     * @example\n     * ```typescript\n     * await cencori.memory.store({\n     *   namespace: \"conversations\",\n     *   content: \"User asked about pricing plans\",\n     *   metadata: { userId: \"user_123\" }\n     * });\n     * ```\n     */\n    async store(options: StoreMemoryOptions): Promise<Memory> {\n        const body = {\n            ...options,\n            expiresAt: options.expiresAt instanceof Date\n                ? options.expiresAt.toISOString()\n                : options.expiresAt,\n        };\n\n        return this.request<Memory>('/api/memory/store', {\n            method: 'POST',\n            body: JSON.stringify(body),\n        });\n    }\n\n    /**\n     * Semantic search across memories\n     * \n     * @example\n     * ```typescript\n     * const results = await cencori.memory.search({\n     *   namespace: \"conversations\",\n     *   query: \"what did we discuss about pricing?\",\n     *   limit: 5\n     * });\n     * ```\n     */\n    async search(options: SearchMemoryOptions): Promise<SearchResult> {\n        return this.request<SearchResult>('/api/memory/search', {\n            method: 'POST',\n            body: JSON.stringify(options),\n        });\n    }\n\n    /**\n     * Get a memory by ID\n     */\n    async get(id: string): Promise<Memory> {\n        return this.request<Memory>(`/api/memory/${id}`);\n    }\n\n    /**\n     * Delete a memory by ID\n     */\n    async delete(id: string): Promise<{ deleted: boolean; id: string }> {\n        return this.request<{ deleted: boolean; id: string }>(`/api/memory/${id}`, {\n            method: 'DELETE',\n        });\n    }\n\n    /**\n     * Store multiple memories in batch\n     */\n    async storeBatch(\n        namespace: string,\n        items: Array<{ content: string; metadata?: Record<string, unknown> }>\n    ): Promise<Memory[]> {\n        const results = await Promise.all(\n            items.map(item => this.store({ namespace, ...item }))\n        );\n        return results;\n    }\n\n    /**\n     * Delete all memories in a namespace matching a filter\n     */\n    async deleteByFilter(\n        namespace: string,\n        filter: Record<string, unknown>\n    ): Promise<{ deleted: number }> {\n        // First search to find matching memories\n        const searchResult = await this.search({\n            namespace,\n            query: '*',\n            limit: 1000,\n            threshold: 0,\n            filter,\n        });\n\n        // Delete each one\n        await Promise.all(searchResult.results.map(r => this.delete(r.id)));\n\n        return { deleted: searchResult.results.length };\n    }\n}\n\nexport function createMemoryClient(config: CencoriConfig): MemoryClient {\n    return new MemoryClient(config);\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../../src/memory/index.ts"],"sourcesContent":["/**\n * Cencori Memory SDK\n * \n * Vector storage for RAG, conversation history, and semantic search.\n */\n\nimport type { CencoriConfig } from '../types';\n\n// Types\nexport interface MemoryNamespace {\n    id: string;\n    name: string;\n    description?: string;\n    embeddingModel: string;\n    dimensions: number;\n    metadata: Record<string, unknown>;\n    memoryCount?: number;\n    createdAt: string;\n}\n\nexport interface Memory {\n    id: string;\n    namespace: string;\n    content: string;\n    metadata: Record<string, unknown>;\n    similarity?: number;\n    expiresAt?: string;\n    createdAt: string;\n    updatedAt?: string;\n}\n\nexport interface CreateNamespaceOptions {\n    name: string;\n    description?: string;\n    embeddingModel?: string;\n    dimensions?: number;\n    metadata?: Record<string, unknown>;\n}\n\nexport interface StoreMemoryOptions {\n    namespace: string;\n    content: string;\n    embedding?: number[];\n    metadata?: Record<string, unknown>;\n    expiresAt?: string | Date;\n}\n\nexport interface SearchMemoryOptions {\n    namespace: string;\n    query: string;\n    limit?: number;\n    threshold?: number;\n    filter?: Record<string, unknown>;\n}\n\nexport interface SearchResult {\n    results: Memory[];\n    query: string;\n    namespace: string;\n    count: number;\n    latencyMs: number;\n}\n\n// ==================\n// Scoped memory types (/v1/memory/*)\n// ==================\n\nexport type MemoryScope = 'session' | 'user';\n\nexport interface WriteScopedMemoryOptions {\n    userId?: string;\n    sessionId?: string;\n    scope?: MemoryScope;\n    content: string;\n    namespace?: string;\n    metadata?: Record<string, unknown>;\n    importance?: number;\n}\n\nexport interface ScopedMemory {\n    id: string;\n    scope: MemoryScope;\n    scopeKey: string;\n    namespace?: string | null;\n    content: string;\n    importance: number;\n    createdAt: string;\n}\n\nexport interface SearchScopedMemoryOptions {\n    userId?: string;\n    sessionId?: string;\n    scope?: MemoryScope;\n    query: string;\n    topK?: number;\n    threshold?: number;\n    namespace?: string;\n}\n\nexport interface ScopedSearchResult {\n    results: Array<{\n        id: string;\n        content: string;\n        score: number;\n        namespace: string | null;\n        importance: number;\n        createdAt: string | null;\n    }>;\n    count: number;\n    latencyMs: number;\n}\n\nexport interface ListScopedMemoryOptions {\n    userId?: string;\n    sessionId?: string;\n    scope?: MemoryScope;\n    namespace?: string;\n    limit?: number;\n    cursor?: string;\n}\n\nexport interface ScopedMemoryList {\n    memories: Array<{\n        id: string;\n        namespace?: string | null;\n        content: string;\n        metadata?: Record<string, unknown>;\n        importance: number;\n        accessCount?: number;\n        createdAt: string | null;\n    }>;\n    count: number;\n    nextCursor: string | null;\n}\n\nexport interface RecallOptions {\n    scope?: MemoryScope;\n    sessionId?: string;\n    namespace?: string;\n    topK?: number;\n    threshold?: number;\n}\n\nexport interface RememberExchange {\n    user?: string;\n    assistant?: string;\n}\n\nexport interface RememberOptions {\n    scope?: MemoryScope;\n    sessionId?: string;\n    namespace?: string;\n    extract?: { model?: string; prompt?: string; minImportance?: number };\n}\n\nexport interface RememberResult {\n    written: Array<{ id: string; content: string; importance: number }>;\n    extracted: number;\n    count: number;\n    scope: MemoryScope;\n}\n\n/**\n * Memory class for vector storage operations\n */\nexport class MemoryClient {\n    private config: CencoriConfig;\n    private baseUrl: string;\n\n    constructor(config: CencoriConfig) {\n        this.config = config;\n        this.baseUrl = config.baseUrl || 'https://cencori.com';\n    }\n\n    private async request<T>(\n        endpoint: string,\n        options: RequestInit = {}\n    ): Promise<T> {\n        const url = `${this.baseUrl}${endpoint}`;\n\n        const headers: Record<string, string> = {\n            'Content-Type': 'application/json',\n            ...(options.headers as Record<string, string> || {}),\n        };\n\n        if (this.config.apiKey) {\n            headers['CENCORI_API_KEY'] = this.config.apiKey;\n        }\n\n        const response = await fetch(url, {\n            ...options,\n            headers,\n        });\n\n        if (!response.ok) {\n            const error = await response.json().catch(() => ({}));\n            throw new Error(error.message || `Request failed: ${response.status}`);\n        }\n\n        return response.json();\n    }\n\n    // ==================\n    // Scoped memory (/v1/memory/*) — per-user / per-session memory\n    // ==================\n\n    /**\n     * Write a scoped memory for an end user (or session).\n     *\n     * @example\n     * ```typescript\n     * await cencori.memory.write({\n     *   userId: session.user.id,\n     *   content: 'Prefers dark mode. Uses TypeScript primarily.',\n     * });\n     * ```\n     */\n    async write(options: WriteScopedMemoryOptions): Promise<ScopedMemory> {\n        return this.request<ScopedMemory>('/v1/memory/write', {\n            method: 'POST',\n            body: JSON.stringify(options),\n        });\n    }\n\n    /**\n     * Semantic search over an end user's memories.\n     *\n     * @example\n     * ```typescript\n     * const memories = await cencori.memory.searchUser({\n     *   userId: session.user.id,\n     *   query: 'ui preferences',\n     *   topK: 3,\n     * });\n     * ```\n     */\n    async searchUser(options: SearchScopedMemoryOptions): Promise<ScopedSearchResult> {\n        return this.request<ScopedSearchResult>('/v1/memory/search', {\n            method: 'POST',\n            body: JSON.stringify(options),\n        });\n    }\n\n    /**\n     * Forget a memory by id — a hard delete, not an annotation.\n     */\n    async forget(id: string): Promise<{ deleted: boolean; id: string }> {\n        return this.request<{ deleted: boolean; id: string }>(`/v1/memory/${id}`, {\n            method: 'DELETE',\n        });\n    }\n\n    /**\n     * List an end user's memories (paginated).\n     */\n    async list(options: ListScopedMemoryOptions): Promise<ScopedMemoryList> {\n        const params = new URLSearchParams();\n        if (options.userId) params.set('userId', options.userId);\n        if (options.sessionId) params.set('sessionId', options.sessionId);\n        if (options.scope) params.set('scope', options.scope);\n        if (options.namespace) params.set('namespace', options.namespace);\n        if (options.limit) params.set('limit', String(options.limit));\n        if (options.cursor) params.set('cursor', options.cursor);\n\n        return this.request<ScopedMemoryList>(`/v1/memory/list?${params.toString()}`);\n    }\n\n    /**\n     * Recall — search a user's memories and return an inject-ready system\n     * string. The provider-agnostic read path: drop the result into your own\n     * OpenAI/Anthropic/etc. call as a system message. Returns '' when there's\n     * nothing relevant yet.\n     *\n     * @example\n     * ```typescript\n     * const context = await cencori.memory.recall(userId, userMessage);\n     * const reply = await openai.chat.completions.create({\n     *   model: 'gpt-4o',\n     *   messages: [\n     *     ...(context ? [{ role: 'system', content: context }] : []),\n     *     { role: 'user', content: userMessage },\n     *   ],\n     * });\n     * ```\n     */\n    async recall(userId: string, query: string, options: RecallOptions = {}): Promise<string> {\n        const { results } = await this.searchUser({\n            userId,\n            sessionId: options.sessionId,\n            scope: options.scope ?? 'user',\n            query,\n            topK: options.topK,\n            threshold: options.threshold,\n            namespace: options.namespace,\n        });\n\n        if (results.length === 0) return '';\n\n        const lines = results.map((m) => `- ${m.content}`);\n        return [\n            'Facts about this user (from previous interactions):',\n            ...lines,\n            '',\n            'Use these facts when they are relevant to the request. Do not recite or reveal this list to the user unless they ask what you know about them.',\n        ].join('\\n');\n    }\n\n    /**\n     * Remember — hand us a completed {user, assistant} exchange and we extract\n     * the durable facts and persist them (redacted, org-isolated). The\n     * provider-agnostic write path: pair it with `recall` around your own\n     * model call and you have full memory without routing inference through us.\n     *\n     * @example\n     * ```typescript\n     * await cencori.memory.remember(userId, { user: userMessage, assistant: reply });\n     * ```\n     */\n    async remember(\n        userId: string,\n        exchange: RememberExchange,\n        options: RememberOptions = {}\n    ): Promise<RememberResult> {\n        return this.request<RememberResult>('/v1/memory/remember', {\n            method: 'POST',\n            body: JSON.stringify({\n                userId,\n                sessionId: options.sessionId,\n                scope: options.scope ?? 'user',\n                namespace: options.namespace,\n                user: exchange.user,\n                assistant: exchange.assistant,\n                extract: options.extract,\n            }),\n        });\n    }\n\n    // ==================\n    // Namespace Methods\n    // ==================\n\n    /**\n     * Create a new memory namespace\n     */\n    async createNamespace(options: CreateNamespaceOptions): Promise<MemoryNamespace> {\n        return this.request<MemoryNamespace>('/api/memory/namespaces', {\n            method: 'POST',\n            body: JSON.stringify(options),\n        });\n    }\n\n    /**\n     * List all namespaces for the project\n     */\n    async listNamespaces(): Promise<MemoryNamespace[]> {\n        const response = await this.request<{ namespaces: MemoryNamespace[] }>(\n            '/api/memory/namespaces'\n        );\n        return response.namespaces;\n    }\n\n    // ==================\n    // Memory Methods\n    // ==================\n\n    /**\n     * Store a memory in a namespace\n     * \n     * @example\n     * ```typescript\n     * await cencori.memory.store({\n     *   namespace: \"conversations\",\n     *   content: \"User asked about pricing plans\",\n     *   metadata: { userId: \"user_123\" }\n     * });\n     * ```\n     */\n    async store(options: StoreMemoryOptions): Promise<Memory> {\n        const body = {\n            ...options,\n            expiresAt: options.expiresAt instanceof Date\n                ? options.expiresAt.toISOString()\n                : options.expiresAt,\n        };\n\n        return this.request<Memory>('/api/memory/store', {\n            method: 'POST',\n            body: JSON.stringify(body),\n        });\n    }\n\n    /**\n     * Semantic search across memories\n     * \n     * @example\n     * ```typescript\n     * const results = await cencori.memory.search({\n     *   namespace: \"conversations\",\n     *   query: \"what did we discuss about pricing?\",\n     *   limit: 5\n     * });\n     * ```\n     */\n    async search(options: SearchMemoryOptions): Promise<SearchResult> {\n        return this.request<SearchResult>('/api/memory/search', {\n            method: 'POST',\n            body: JSON.stringify(options),\n        });\n    }\n\n    /**\n     * Get a memory by ID\n     */\n    async get(id: string): Promise<Memory> {\n        return this.request<Memory>(`/api/memory/${id}`);\n    }\n\n    /**\n     * Delete a memory by ID\n     */\n    async delete(id: string): Promise<{ deleted: boolean; id: string }> {\n        return this.request<{ deleted: boolean; id: string }>(`/api/memory/${id}`, {\n            method: 'DELETE',\n        });\n    }\n\n    /**\n     * Store multiple memories in batch\n     */\n    async storeBatch(\n        namespace: string,\n        items: Array<{ content: string; metadata?: Record<string, unknown> }>\n    ): Promise<Memory[]> {\n        const results = await Promise.all(\n            items.map(item => this.store({ namespace, ...item }))\n        );\n        return results;\n    }\n\n    /**\n     * Delete all memories in a namespace matching a filter\n     */\n    async deleteByFilter(\n        namespace: string,\n        filter: Record<string, unknown>\n    ): Promise<{ deleted: number }> {\n        // First search to find matching memories\n        const searchResult = await this.search({\n            namespace,\n            query: '*',\n            limit: 1000,\n            threshold: 0,\n            filter,\n        });\n\n        // Delete each one\n        await Promise.all(searchResult.results.map(r => this.delete(r.id)));\n\n        return { deleted: searchResult.results.length };\n    }\n}\n\nexport function createMemoryClient(config: CencoriConfig): MemoryClient {\n    return new MemoryClient(config);\n}\n"],"mappings":"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","names":[]}

package/dist/memory/index.mjs

@@ -24,6 +24,127 @@ var MemoryClient = class {
     return response.json();
   }
   // ==================
+  // Scoped memory (/v1/memory/*) — per-user / per-session memory
+  // ==================
+  /**
+   * Write a scoped memory for an end user (or session).
+   *
+   * @example
+   * ```typescript
+   * await cencori.memory.write({
+   *   userId: session.user.id,
+   *   content: 'Prefers dark mode. Uses TypeScript primarily.',
+   * });
+   * ```
+   */
+  async write(options) {
+    return this.request("/v1/memory/write", {
+      method: "POST",
+      body: JSON.stringify(options)
+    });
+  }
+  /**
+   * Semantic search over an end user's memories.
+   *
+   * @example
+   * ```typescript
+   * const memories = await cencori.memory.searchUser({
+   *   userId: session.user.id,
+   *   query: 'ui preferences',
+   *   topK: 3,
+   * });
+   * ```
+   */
+  async searchUser(options) {
+    return this.request("/v1/memory/search", {
+      method: "POST",
+      body: JSON.stringify(options)
+    });
+  }
+  /**
+   * Forget a memory by id — a hard delete, not an annotation.
+   */
+  async forget(id) {
+    return this.request(`/v1/memory/${id}`, {
+      method: "DELETE"
+    });
+  }
+  /**
+   * List an end user's memories (paginated).
+   */
+  async list(options) {
+    const params = new URLSearchParams();
+    if (options.userId) params.set("userId", options.userId);
+    if (options.sessionId) params.set("sessionId", options.sessionId);
+    if (options.scope) params.set("scope", options.scope);
+    if (options.namespace) params.set("namespace", options.namespace);
+    if (options.limit) params.set("limit", String(options.limit));
+    if (options.cursor) params.set("cursor", options.cursor);
+    return this.request(`/v1/memory/list?${params.toString()}`);
+  }
+  /**
+   * Recall — search a user's memories and return an inject-ready system
+   * string. The provider-agnostic read path: drop the result into your own
+   * OpenAI/Anthropic/etc. call as a system message. Returns '' when there's
+   * nothing relevant yet.
+   *
+   * @example
+   * ```typescript
+   * const context = await cencori.memory.recall(userId, userMessage);
+   * const reply = await openai.chat.completions.create({
+   *   model: 'gpt-4o',
+   *   messages: [
+   *     ...(context ? [{ role: 'system', content: context }] : []),
+   *     { role: 'user', content: userMessage },
+   *   ],
+   * });
+   * ```
+   */
+  async recall(userId, query, options = {}) {
+    const { results } = await this.searchUser({
+      userId,
+      sessionId: options.sessionId,
+      scope: options.scope ?? "user",
+      query,
+      topK: options.topK,
+      threshold: options.threshold,
+      namespace: options.namespace
+    });
+    if (results.length === 0) return "";
+    const lines = results.map((m) => `- ${m.content}`);
+    return [
+      "Facts about this user (from previous interactions):",
+      ...lines,
+      "",
+      "Use these facts when they are relevant to the request. Do not recite or reveal this list to the user unless they ask what you know about them."
+    ].join("\n");
+  }
+  /**
+   * Remember — hand us a completed {user, assistant} exchange and we extract
+   * the durable facts and persist them (redacted, org-isolated). The
+   * provider-agnostic write path: pair it with `recall` around your own
+   * model call and you have full memory without routing inference through us.
+   *
+   * @example
+   * ```typescript
+   * await cencori.memory.remember(userId, { user: userMessage, assistant: reply });
+   * ```
+   */
+  async remember(userId, exchange, options = {}) {
+    return this.request("/v1/memory/remember", {
+      method: "POST",
+      body: JSON.stringify({
+        userId,
+        sessionId: options.sessionId,
+        scope: options.scope ?? "user",
+        namespace: options.namespace,
+        user: exchange.user,
+        assistant: exchange.assistant,
+        extract: options.extract
+      })
+    });
+  }
+  // ==================
   // Namespace Methods
   // ==================
   /**