@papr/memory 1.20.0 → 2.0.0

package/src/resources/messages/index.ts

@@ -0,0 +1,11 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export { Messages, type MessageStoreResponse, type MessageStoreParams } from './messages';
+export {
+  Sessions,
+  type SessionCompressResponse,
+  type SessionProcessResponse,
+  type SessionRetrieveHistoryResponse,
+  type SessionRetrieveStatusResponse,
+  type SessionRetrieveHistoryParams,
+} from './sessions';

package/src/resources/messages/messages.ts

@@ -0,0 +1,193 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../core/resource';
+import * as MemoryAPI from '../memory';
+import * as Shared from '../shared';
+import * as SessionsAPI from './sessions';
+import {
+  SessionCompressResponse,
+  SessionProcessResponse,
+  SessionRetrieveHistoryParams,
+  SessionRetrieveHistoryResponse,
+  SessionRetrieveStatusResponse,
+  Sessions,
+} from './sessions';
+import { APIPromise } from '../../core/api-promise';
+import { RequestOptions } from '../../internal/request-options';
+
+export class Messages extends APIResource {
+  sessions: SessionsAPI.Sessions = new SessionsAPI.Sessions(this._client);
+
+  /**
+   * Store a chat message and queue it for AI analysis and memory creation.
+   *
+   *     **Authentication Required**: Bearer token, API key, or session token
+   *
+   *     **Processing Control**:
+   *     - Set `process_messages: true` (default) to enable full AI analysis and memory creation
+   *     - Set `process_messages: false` to store messages only without processing into memories
+   *
+   *     **Processing Flow** (when process_messages=true):
+   *     1. Message is immediately stored in PostMessage class
+   *     2. Background processing analyzes the message for memory-worthiness
+   *     3. If worthy, creates a memory with appropriate role-based categorization
+   *     4. Links the message to the created memory
+   *
+   *     **Role-Based Categories**:
+   *     - **User messages**: preference, task, goal, facts, context
+   *     - **Assistant messages**: skills, learning
+   *
+   *     **Session Management**:
+   *     - `sessionId` is required to group related messages
+   *     - Use the same `sessionId` for an entire conversation
+   *     - **Optional `title`**: Set a human-readable title for the conversation (e.g., "Q4 Planning Session")
+   *     - Retrieve conversation history using GET /messages/sessions/{sessionId}
+   *
+   * @example
+   * ```ts
+   * const response = await client.messages.store({
+   *   content: 'string',
+   *   role: 'user',
+   *   sessionId: 'sessionId',
+   * });
+   * ```
+   */
+  store(body: MessageStoreParams, options?: RequestOptions): APIPromise<MessageStoreResponse> {
+    return this._client.post('/v1/messages', { body, ...options });
+  }
+}
+
+/**
+ * Response model for message storage
+ */
+export interface MessageStoreResponse {
+  /**
+   * Content of the message - can be a simple string or structured content objects
+   */
+  content: string | Array<{ [key: string]: unknown }>;
+
+  /**
+   * When the message was created
+   */
+  createdAt: string;
+
+  /**
+   * Parse Server objectId of the stored message
+   */
+  objectId: string;
+
+  /**
+   * Role of the message sender
+   */
+  role: 'user' | 'assistant';
+
+  /**
+   * Session ID of the conversation
+   */
+  sessionId: string;
+
+  /**
+   * Status of background processing (queued, analyzing, completed, failed)
+   */
+  processing_status?: string;
+}
+
+export interface MessageStoreParams {
+  /**
+   * The content of the chat message - can be a simple string or structured content
+   * objects
+   */
+  content: string | Array<{ [key: string]: unknown }>;
+
+  /**
+   * Role of the message sender (user or assistant)
+   */
+  role: 'user' | 'assistant';
+
+  /**
+   * Session ID to group related messages in a conversation
+   */
+  sessionId: string;
+
+  /**
+   * Optional context for the message (conversation history or relevant context)
+   */
+  context?: Array<{ [key: string]: unknown }> | null;
+
+  /**
+   * Graph generation configuration
+   */
+  graph_generation?: MemoryAPI.GraphGeneration | null;
+
+  /**
+   * Unified memory processing policy.
+   *
+   * This is the SINGLE source of truth for how a memory should be processed,
+   * combining graph generation control AND OMO (Open Memory Object) safety
+   * standards.
+   *
+   * **Graph Generation Modes:**
+   *
+   * - auto: LLM extracts entities freely (default)
+   * - manual: Developer provides exact nodes (no LLM extraction)
+   *
+   * **OMO Safety Standards:**
+   *
+   * - consent: How data owner allowed storage (explicit, implicit, terms, none)
+   * - risk: Safety assessment (none, sensitive, flagged)
+   * - acl: Access control list for read/write permissions
+   *
+   * **Schema Integration:**
+   *
+   * - schema_id: Reference a schema that may have its own default memory_policy
+   * - Schema-level policies are merged with request-level (request takes precedence)
+   */
+  memory_policy?: Shared.MemoryPolicy | null;
+
+  /**
+   * Metadata for memory request
+   */
+  metadata?: MemoryAPI.MemoryMetadata | null;
+
+  /**
+   * Optional namespace ID for multi-tenant message scoping
+   */
+  namespace_id?: string | null;
+
+  /**
+   * Optional organization ID for multi-tenant message scoping
+   */
+  organization_id?: string | null;
+
+  /**
+   * Whether to process messages into memories (true) or just store them (false).
+   * Default is true.
+   */
+  process_messages?: boolean;
+
+  /**
+   * Optional array of relationships for Graph DB (Neo4j)
+   */
+  relationships_json?: Array<{ [key: string]: unknown }> | null;
+
+  /**
+   * Optional title for the conversation session. Sets the Chat.title in Parse Server
+   * for easy identification.
+   */
+  title?: string | null;
+}
+
+Messages.Sessions = Sessions;
+
+export declare namespace Messages {
+  export { type MessageStoreResponse as MessageStoreResponse, type MessageStoreParams as MessageStoreParams };
+
+  export {
+    Sessions as Sessions,
+    type SessionCompressResponse as SessionCompressResponse,
+    type SessionProcessResponse as SessionProcessResponse,
+    type SessionRetrieveHistoryResponse as SessionRetrieveHistoryResponse,
+    type SessionRetrieveStatusResponse as SessionRetrieveStatusResponse,
+    type SessionRetrieveHistoryParams as SessionRetrieveHistoryParams,
+  };
+}

package/src/resources/messages/sessions.ts

@@ -0,0 +1,315 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../core/resource';
+import { APIPromise } from '../../core/api-promise';
+import { RequestOptions } from '../../internal/request-options';
+import { path } from '../../internal/utils/path';
+
+export class Sessions extends APIResource {
+  /**
+   * Get compressed conversation context for a session.
+   *
+   *     Compress your conversation into hierarchical summaries with rich metadata,
+   *     perfect for reducing token usage in LLM context windows.
+   *
+   *     **Authentication Required**: Bearer token, API key, or session token
+   *
+   *     **What it returns**:
+   *     - **short_term**: Last 15 messages compressed
+   *     - **medium_term**: Last ~100 messages compressed
+   *     - **long_term**: Full session compressed
+   *     - **topics**: Key topics discussed
+   *     - **enhanced_fields**: Project context, tech stack, key decisions, next steps, files accessed
+   *
+   *     **Perfect for**:
+   *     - Reducing token usage in LLM prompts (96% savings)
+   *     - Providing conversation context without full history
+   *     - Quick conversation overview for AI agents
+   *     - Project documentation and status snapshots
+   *
+   *     **Input**: Just the session ID - all context is extracted automatically
+   *
+   * @example
+   * ```ts
+   * const response = await client.messages.sessions.compress(
+   *   'session_id',
+   * );
+   * ```
+   */
+  compress(sessionID: string, options?: RequestOptions): APIPromise<SessionCompressResponse> {
+    return this._client.get(path`/v1/messages/sessions/${sessionID}/compress`, options);
+  }
+
+  /**
+   * Process all stored messages in a session that were previously stored with
+   * process_messages=false.
+   *
+   *     **Authentication Required**: Bearer token, API key, or session token
+   *
+   *     This endpoint allows you to retroactively process messages that were initially stored
+   *     without processing. Useful for:
+   *     - Processing messages after deciding you want them as memories
+   *     - Batch processing large conversation sessions
+   *     - Re-processing sessions with updated AI models
+   *
+   *     **Processing Behavior**:
+   *     - Only processes messages with status 'stored_only' or 'pending'
+   *     - Uses the same smart batch analysis (every 15 messages)
+   *     - Respects existing memory creation pipeline
+   *
+   * @example
+   * ```ts
+   * const response = await client.messages.sessions.process(
+   *   'session_id',
+   * );
+   * ```
+   */
+  process(sessionID: string, options?: RequestOptions): APIPromise<unknown> {
+    return this._client.post(path`/v1/messages/sessions/${sessionID}/process`, options);
+  }
+
+  /**
+   * Retrieve message history for a specific conversation session.
+   *
+   *     **Authentication Required**: Bearer token, API key, or session token
+   *
+   *     **Pagination**:
+   *     - Use `limit` and `skip` parameters for pagination
+   *     - Messages are returned in chronological order (oldest first)
+   *     - `total_count` indicates total messages in the session
+   *
+   *     **Summaries** (if available):
+   *     - Returns hierarchical conversation summaries (short/medium/long-term)
+   *     - Includes `context_for_llm` field with pre-compressed context
+   *     - Summaries are automatically generated every 15 messages
+   *     - Use `/sessions/{session_id}/compress` endpoint to retrieve on-demand
+   *
+   *     **Access Control**:
+   *     - Only returns messages for the authenticated user
+   *     - Workspace scoping is applied if available
+   *
+   * @example
+   * ```ts
+   * const response =
+   *   await client.messages.sessions.retrieveHistory(
+   *     'session_id',
+   *   );
+   * ```
+   */
+  retrieveHistory(
+    sessionID: string,
+    query: SessionRetrieveHistoryParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<SessionRetrieveHistoryResponse> {
+    return this._client.get(path`/v1/messages/sessions/${sessionID}`, { query, ...options });
+  }
+
+  /**
+   * Get processing status for messages in a session.
+   *
+   *     **Authentication Required**: Bearer token, API key, or session token
+   *
+   *     **Status Information**:
+   *     - Total messages in session
+   *     - Processing status breakdown (queued, analyzing, completed, failed)
+   *     - Any messages with processing errors
+   *
+   * @example
+   * ```ts
+   * const response =
+   *   await client.messages.sessions.retrieveStatus(
+   *     'session_id',
+   *   );
+   * ```
+   */
+  retrieveStatus(sessionID: string, options?: RequestOptions): APIPromise<unknown> {
+    return this._client.get(path`/v1/messages/sessions/${sessionID}/status`, options);
+  }
+}
+
+/**
+ * Response model for session summarization endpoint
+ */
+export interface SessionCompressResponse {
+  /**
+   * Instructions for AI agents on how to search for more details about this
+   * conversation
+   */
+  ai_agent_note: string;
+
+  /**
+   * Whether summaries were retrieved from cache (true) or just generated (false)
+   */
+  from_cache: boolean;
+
+  /**
+   * Session ID of the conversation
+   */
+  session_id: string;
+
+  /**
+   * Hierarchical conversation summaries
+   */
+  summaries: SessionCompressResponse.Summaries;
+
+  /**
+   * Number of messages summarized (only present if just generated)
+   */
+  message_count?: number | null;
+}
+
+export namespace SessionCompressResponse {
+  /**
+   * Hierarchical conversation summaries
+   */
+  export interface Summaries {
+    /**
+     * When summaries were last updated
+     */
+    last_updated?: string | null;
+
+    /**
+     * Full session summary
+     */
+    long_term?: string | null;
+
+    /**
+     * Summary of last ~100 messages
+     */
+    medium_term?: string | null;
+
+    /**
+     * Summary of last 15 messages
+     */
+    short_term?: string | null;
+
+    /**
+     * Key topics discussed
+     */
+    topics?: Array<string>;
+  }
+}
+
+export type SessionProcessResponse = unknown;
+
+/**
+ * Response model for retrieving message history
+ */
+export interface SessionRetrieveHistoryResponse {
+  /**
+   * List of messages in chronological order
+   */
+  messages: Array<SessionRetrieveHistoryResponse.Message>;
+
+  /**
+   * Session ID of the conversation
+   */
+  sessionId: string;
+
+  /**
+   * Total number of messages in the session
+   */
+  total_count: number;
+
+  /**
+   * Pre-formatted compressed context ready for LLM consumption (summaries + recent
+   * messages)
+   */
+  context_for_llm?: string | null;
+
+  /**
+   * Hierarchical conversation summaries for context window compression
+   */
+  summaries?: SessionRetrieveHistoryResponse.Summaries | null;
+}
+
+export namespace SessionRetrieveHistoryResponse {
+  /**
+   * Response model for message storage
+   */
+  export interface Message {
+    /**
+     * Content of the message - can be a simple string or structured content objects
+     */
+    content: string | Array<{ [key: string]: unknown }>;
+
+    /**
+     * When the message was created
+     */
+    createdAt: string;
+
+    /**
+     * Parse Server objectId of the stored message
+     */
+    objectId: string;
+
+    /**
+     * Role of the message sender
+     */
+    role: 'user' | 'assistant';
+
+    /**
+     * Session ID of the conversation
+     */
+    sessionId: string;
+
+    /**
+     * Status of background processing (queued, analyzing, completed, failed)
+     */
+    processing_status?: string;
+  }
+
+  /**
+   * Hierarchical conversation summaries for context window compression
+   */
+  export interface Summaries {
+    /**
+     * When summaries were last updated
+     */
+    last_updated?: string | null;
+
+    /**
+     * Full session summary
+     */
+    long_term?: string | null;
+
+    /**
+     * Summary of last ~100 messages
+     */
+    medium_term?: string | null;
+
+    /**
+     * Summary of last 15 messages
+     */
+    short_term?: string | null;
+
+    /**
+     * Key topics discussed
+     */
+    topics?: Array<string>;
+  }
+}
+
+export type SessionRetrieveStatusResponse = unknown;
+
+export interface SessionRetrieveHistoryParams {
+  /**
+   * Maximum number of messages to return
+   */
+  limit?: number;
+
+  /**
+   * Number of messages to skip for pagination
+   */
+  skip?: number;
+}
+
+export declare namespace Sessions {
+  export {
+    type SessionCompressResponse as SessionCompressResponse,
+    type SessionProcessResponse as SessionProcessResponse,
+    type SessionRetrieveHistoryResponse as SessionRetrieveHistoryResponse,
+    type SessionRetrieveStatusResponse as SessionRetrieveStatusResponse,
+    type SessionRetrieveHistoryParams as SessionRetrieveHistoryParams,
+  };
+}

package/src/resources/messages.ts

@@ -0,0 +1,3 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export * from './messages/index';

package/src/resources/omo.ts

@@ -0,0 +1,132 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../core/resource';
+import { APIPromise } from '../core/api-promise';
+import { RequestOptions } from '../internal/request-options';
+
+export class Omo extends APIResource {
+  /**
+   * Export memories in Open Memory Object (OMO) standard format.
+   *
+   *     This enables memory portability to other OMO-compliant platforms.
+   *     The exported format follows the OMO v1 schema.
+   *
+   *     **OMO Standard:** https://github.com/papr-ai/open-memory-object
+   */
+  exportMemories(
+    body: OmoExportMemoriesParams,
+    options?: RequestOptions,
+  ): APIPromise<OmoExportMemoriesResponse> {
+    return this._client.post('/v1/omo/export', { body, ...options });
+  }
+
+  /**
+   * Export memories in OMO JSON file format for download.
+   */
+  exportMemoriesAsJson(query: OmoExportMemoriesAsJsonParams, options?: RequestOptions): APIPromise<unknown> {
+    return this._client.get('/v1/omo/export.json', { query, ...options });
+  }
+
+  /**
+   * Import memories from Open Memory Object (OMO) standard format.
+   *
+   *     This enables importing memories from other OMO-compliant platforms.
+   *
+   *     **OMO Standard:** https://github.com/papr-ai/open-memory-object
+   */
+  importMemories(
+    body: OmoImportMemoriesParams,
+    options?: RequestOptions,
+  ): APIPromise<OmoImportMemoriesResponse> {
+    return this._client.post('/v1/omo/import', { body, ...options });
+  }
+}
+
+/**
+ * Response model for OMO export.
+ */
+export interface OmoExportMemoriesResponse {
+  /**
+   * Number of memories exported
+   */
+  count: number;
+
+  /**
+   * Memories in OMO v1 format
+   */
+  memories: Array<{ [key: string]: unknown }>;
+
+  code?: number;
+
+  error?: string | null;
+
+  status?: string;
+}
+
+export type OmoExportMemoriesAsJsonResponse = unknown;
+
+/**
+ * Response model for OMO import.
+ */
+export interface OmoImportMemoriesResponse {
+  /**
+   * Number of memories successfully imported
+   */
+  imported: number;
+
+  code?: number;
+
+  /**
+   * Import errors
+   */
+  errors?: Array<{ [key: string]: unknown }>;
+
+  /**
+   * IDs of imported memories
+   */
+  memory_ids?: Array<string>;
+
+  /**
+   * Number of memories skipped (duplicates)
+   */
+  skipped?: number;
+
+  status?: string;
+}
+
+export interface OmoExportMemoriesParams {
+  /**
+   * List of memory IDs to export
+   */
+  memory_ids: Array<string>;
+}
+
+export interface OmoExportMemoriesAsJsonParams {
+  /**
+   * Comma-separated list of memory IDs
+   */
+  memory_ids: string;
+}
+
+export interface OmoImportMemoriesParams {
+  /**
+   * List of memories in OMO v1 format
+   */
+  memories: Array<{ [key: string]: unknown }>;
+
+  /**
+   * Skip memories with IDs that already exist
+   */
+  skip_duplicates?: boolean;
+}
+
+export declare namespace Omo {
+  export {
+    type OmoExportMemoriesResponse as OmoExportMemoriesResponse,
+    type OmoExportMemoriesAsJsonResponse as OmoExportMemoriesAsJsonResponse,
+    type OmoImportMemoriesResponse as OmoImportMemoriesResponse,
+    type OmoExportMemoriesParams as OmoExportMemoriesParams,
+    type OmoExportMemoriesAsJsonParams as OmoExportMemoriesAsJsonParams,
+    type OmoImportMemoriesParams as OmoImportMemoriesParams,
+  };
+}