@sovant/sdk 1.4.2 → 1.4.3

package/README.md

@@ -199,9 +199,51 @@ const recall = await sv.memory.recall({
 console.log(recall.results);
 ```
 
+## List Memories
+
+Fetch memories with filtering and pagination. Use `list()` to retrieve recent memories or filter by criteria — it's more efficient than `search()` when you don't need vector similarity.
+
+```typescript
+// List recent memories
+const { memories, total, has_more } = await sv.memory.list({
+  limit: 20,
+  offset: 0
+});
+
+// Filter by thread
+const threadMemories = await sv.memory.list({
+  thread_id: "thread-uuid",
+  limit: 50
+});
+
+// Filter by type and tags
+const preferences = await sv.memory.list({
+  type: "preference",
+  tags: ["settings"],
+  sort_by: "updated_at",
+  sort_order: "desc"
+});
+
+// Pinned memories only
+const pinned = await sv.memory.list({
+  is_pinned: true
+});
+```
+
+**Available parameters:**
+- `limit` — max results (default: 20, max: 100)
+- `offset` — pagination offset
+- `thread_id` — filter by thread
+- `type` — filter by memory type
+- `tags` — filter by tags (must have all)
+- `is_pinned` — filter by pinned status
+- `is_archived` — filter by archived status
+- `sort_by` — `created_at`, `updated_at`, `importance`, or `type`
+- `sort_order` — `asc` or `desc`
+
 ## Features
 
-- **Memory CRUD** — create, retrieve, update, delete memories
+- **Memory CRUD** — create, list, retrieve, update, delete memories
 - **Semantic Search** — query memories with filters and ranking
 - **Threads** — organize memories into conversations or sessions (fully supported in SDK)
 - **Batch Operations** — create multiple memories in one request
@@ -234,7 +276,9 @@ console.log(recall.results);
 
 ## Versioning & Changelog
 
-- **Current release:** 1.4.1
+- **Current release:** 1.4.3
+- Version 1.4.3 — add `memory.list()` for filtered pagination
+- Version 1.4.2 — README sync
 - Version 1.4.1 — CJS export fix
 - Version 1.4.0 — full threads support (create, list, get, update, delete)
 - Version 1.3.0 — hybrid recall with profile awareness

package/dist/index.cjs

@@ -207,6 +207,37 @@ var Sovant = class {
       return this.req(`/api/v1/memory/recall?${params.toString()}`, {
         method: "GET"
       });
+    },
+    /**
+     * List memories with filtering and pagination
+     * Returns memories ordered by sort criteria (default: created_at desc)
+     *
+     * Use list() to fetch recent memories or filter by criteria.
+     * Use search() for semantic/vector-based queries.
+     * Use recall() for conversational AI queries.
+     *
+     * @param params - Optional filtering and pagination parameters
+     * @returns Paginated list of memories
+     */
+    list: (params) => {
+      const query = new URLSearchParams();
+      if (params?.limit !== void 0)
+        query.append("limit", params.limit.toString());
+      if (params?.offset !== void 0)
+        query.append("offset", params.offset.toString());
+      if (params?.thread_id) query.append("thread_id", params.thread_id);
+      if (params?.type) query.append("type", params.type);
+      if (params?.tags) query.append("tags", params.tags.join(","));
+      if (params?.is_pinned !== void 0)
+        query.append("is_pinned", params.is_pinned.toString());
+      if (params?.is_archived !== void 0)
+        query.append("is_archived", params.is_archived.toString());
+      if (params?.sort_by) query.append("sort_by", params.sort_by);
+      if (params?.sort_order) query.append("sort_order", params.sort_order);
+      return this.req(
+        `/api/v1/memory?${query.toString()}`,
+        { method: "GET" }
+      );
     }
   };
   threads = {

package/dist/index.d.cts

@@ -17,6 +17,60 @@ type SovantClientOptions = {
     }) => void;
     onError?: (err: SovantError) => void;
 };
+/**
+ * Parameters for listing memories
+ */
+type MemoryListParams = {
+    /** Maximum number of memories to return (default: 20, max: 100) */
+    limit?: number;
+    /** Number of memories to skip for pagination (default: 0) */
+    offset?: number;
+    /** Filter by thread ID */
+    thread_id?: string;
+    /** Filter by memory type */
+    type?: "journal" | "insight" | "observation" | "task" | "preference";
+    /** Filter by tags (memories must have all specified tags) */
+    tags?: string[];
+    /** Filter by pinned status */
+    is_pinned?: boolean;
+    /** Filter by archived status */
+    is_archived?: boolean;
+    /** Sort field (default: created_at) */
+    sort_by?: "created_at" | "updated_at" | "importance" | "type";
+    /** Sort direction (default: desc) */
+    sort_order?: "asc" | "desc";
+};
+/**
+ * A memory object returned from the API
+ */
+type Memory = {
+    id: string;
+    content: string;
+    type: string;
+    tags: string[];
+    metadata?: Record<string, any>;
+    thread_id?: string;
+    importance?: number;
+    created_at: string;
+    updated_at: string;
+    is_pinned: boolean;
+    is_archived: boolean;
+};
+/**
+ * Response from memory.list()
+ */
+type MemoryListResponse = {
+    /** Array of memory objects */
+    memories: Memory[];
+    /** Total count of memories matching the filter */
+    total: number;
+    /** Limit used for this query */
+    limit: number;
+    /** Offset used for this query */
+    offset: number;
+    /** Whether more results are available */
+    has_more: boolean;
+};
 declare class Sovant {
     private apiKey;
     private baseUrl;
@@ -97,6 +151,18 @@ declare class Sovant {
             thread_id?: string;
             limit?: number;
         }) => Promise<unknown>;
+        /**
+         * List memories with filtering and pagination
+         * Returns memories ordered by sort criteria (default: created_at desc)
+         *
+         * Use list() to fetch recent memories or filter by criteria.
+         * Use search() for semantic/vector-based queries.
+         * Use recall() for conversational AI queries.
+         *
+         * @param params - Optional filtering and pagination parameters
+         * @returns Paginated list of memories
+         */
+        list: (params?: MemoryListParams) => Promise<MemoryListResponse>;
     };
     threads: {
         /**
@@ -204,4 +270,4 @@ declare class SovantError extends Error {
     constructor(message: string, code: string, status?: number, details?: any);
 }
 
-export { Sovant, type SovantClientOptions, SovantError };
+export { type Memory, type MemoryListParams, type MemoryListResponse, Sovant, type SovantClientOptions, SovantError };

package/dist/index.d.ts

@@ -17,6 +17,60 @@ type SovantClientOptions = {
     }) => void;
     onError?: (err: SovantError) => void;
 };
+/**
+ * Parameters for listing memories
+ */
+type MemoryListParams = {
+    /** Maximum number of memories to return (default: 20, max: 100) */
+    limit?: number;
+    /** Number of memories to skip for pagination (default: 0) */
+    offset?: number;
+    /** Filter by thread ID */
+    thread_id?: string;
+    /** Filter by memory type */
+    type?: "journal" | "insight" | "observation" | "task" | "preference";
+    /** Filter by tags (memories must have all specified tags) */
+    tags?: string[];
+    /** Filter by pinned status */
+    is_pinned?: boolean;
+    /** Filter by archived status */
+    is_archived?: boolean;
+    /** Sort field (default: created_at) */
+    sort_by?: "created_at" | "updated_at" | "importance" | "type";
+    /** Sort direction (default: desc) */
+    sort_order?: "asc" | "desc";
+};
+/**
+ * A memory object returned from the API
+ */
+type Memory = {
+    id: string;
+    content: string;
+    type: string;
+    tags: string[];
+    metadata?: Record<string, any>;
+    thread_id?: string;
+    importance?: number;
+    created_at: string;
+    updated_at: string;
+    is_pinned: boolean;
+    is_archived: boolean;
+};
+/**
+ * Response from memory.list()
+ */
+type MemoryListResponse = {
+    /** Array of memory objects */
+    memories: Memory[];
+    /** Total count of memories matching the filter */
+    total: number;
+    /** Limit used for this query */
+    limit: number;
+    /** Offset used for this query */
+    offset: number;
+    /** Whether more results are available */
+    has_more: boolean;
+};
 declare class Sovant {
     private apiKey;
     private baseUrl;
@@ -97,6 +151,18 @@ declare class Sovant {
             thread_id?: string;
             limit?: number;
         }) => Promise<unknown>;
+        /**
+         * List memories with filtering and pagination
+         * Returns memories ordered by sort criteria (default: created_at desc)
+         *
+         * Use list() to fetch recent memories or filter by criteria.
+         * Use search() for semantic/vector-based queries.
+         * Use recall() for conversational AI queries.
+         *
+         * @param params - Optional filtering and pagination parameters
+         * @returns Paginated list of memories
+         */
+        list: (params?: MemoryListParams) => Promise<MemoryListResponse>;
     };
     threads: {
         /**
@@ -204,4 +270,4 @@ declare class SovantError extends Error {
     constructor(message: string, code: string, status?: number, details?: any);
 }
 
-export { Sovant, type SovantClientOptions, SovantError };
+export { type Memory, type MemoryListParams, type MemoryListResponse, Sovant, type SovantClientOptions, SovantError };

package/dist/index.js

@@ -182,6 +182,37 @@ var Sovant = class {
       return this.req(`/api/v1/memory/recall?${params.toString()}`, {
         method: "GET"
       });
+    },
+    /**
+     * List memories with filtering and pagination
+     * Returns memories ordered by sort criteria (default: created_at desc)
+     *
+     * Use list() to fetch recent memories or filter by criteria.
+     * Use search() for semantic/vector-based queries.
+     * Use recall() for conversational AI queries.
+     *
+     * @param params - Optional filtering and pagination parameters
+     * @returns Paginated list of memories
+     */
+    list: (params) => {
+      const query = new URLSearchParams();
+      if (params?.limit !== void 0)
+        query.append("limit", params.limit.toString());
+      if (params?.offset !== void 0)
+        query.append("offset", params.offset.toString());
+      if (params?.thread_id) query.append("thread_id", params.thread_id);
+      if (params?.type) query.append("type", params.type);
+      if (params?.tags) query.append("tags", params.tags.join(","));
+      if (params?.is_pinned !== void 0)
+        query.append("is_pinned", params.is_pinned.toString());
+      if (params?.is_archived !== void 0)
+        query.append("is_archived", params.is_archived.toString());
+      if (params?.sort_by) query.append("sort_by", params.sort_by);
+      if (params?.sort_order) query.append("sort_order", params.sort_order);
+      return this.req(
+        `/api/v1/memory?${query.toString()}`,
+        { method: "GET" }
+      );
     }
   };
   threads = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sovant/sdk",
-  "version": "1.4.2",
+  "version": "1.4.3",
   "description": "Official Sovant Memory-as-a-Service SDK for JavaScript and TypeScript",
   "type": "module",
   "main": "dist/index.js",