0
# Memory Management
1

2
Comprehensive memory operations for creating, retrieving, updating, and deleting memories with rich metadata support and file upload capabilities.
3

4
## Capabilities
5

6
### Add Memory
7

8
Creates a new memory with content, metadata, and optional container tags for organization.
9

10
```typescript { .api }
11
/**
12
 * Add a memory with any content type (text, url, file, etc.) and metadata
13
 * @param params - Memory creation parameters
14
 * @returns Promise resolving to memory creation response
15
 */
16
add(params?: MemoryAddParams): APIPromise<MemoryAddResponse>;
17

18
interface MemoryAddParams {
19
  /** The content to extract and process into a memory */
20
  content?: string;
21
  /** Optional custom ID from your database */
22
  customId?: string;
23
  /** Key-value metadata for the memory */
24
  metadata?: { [key: string]: string | number | boolean };
25
  /** Single container tag for grouping */
26
  containerTag?: string;
27
  /** @deprecated Use containerTag instead */
28
  containerTags?: string[];
29
}
30

31
interface MemoryAddResponse {
32
  id: string;
33
  status: string;
34
}
35
```
36

37
**Usage Examples:**
38

39
```typescript
40
import Supermemory from "supermemory";
41

42
const client = new Supermemory({ apiKey: "your-api-key" });
43

44
// Add text memory
45
const textMemory = await client.memories.add({
46
  content: "Machine learning is a subset of AI",
47
  metadata: { category: "education", topic: "ai" },
48
  containerTag: "user_123",
49
});
50

51
// Add URL memory
52
const urlMemory = await client.memories.add({
53
  content: "https://example.com/article",
54
  customId: "article_456",
55
  metadata: { source: "web", priority: 1 },
56
});
57
```
58

59
### Get Memory
60

61
Retrieves a complete memory object by ID including all content and metadata.
62

63
```typescript { .api }
64
/**
65
 * Get a memory by ID
66
 * @param id - Unique memory identifier
67
 * @returns Promise resolving to complete memory object
68
 */
69
get(id: string): APIPromise<MemoryGetResponse>;
70

71
interface MemoryGetResponse {
72
  id: string;
73
  connectionId: string | null;
74
  content: string | null;
75
  createdAt: string;
76
  customId: string | null;
77
  metadata: string | number | boolean | { [key: string]: unknown } | Array<unknown> | null;
78
  ogImage: string | null;
79
  source: string | null;
80
  status: MemoryStatus;
81
  summary: string | null;
82
  summaryEmbeddingModel: string | null;
83
  summaryEmbeddingModelNew: string | null;
84
  summaryEmbeddingNew: number[] | null;
85
  title: string | null;
86
  type: MemoryType;
87
  updatedAt: string;
88
  containerTags?: string[];
89
  raw?: null;
90
  url?: string | null;
91
}
92
```
93

94
**Usage Example:**
95

96
```typescript
97
const memory = await client.memories.get("memory-id-123");
98
console.log(memory.title, memory.status, memory.summary);
99
```
100

101
### Update Memory
102

103
Updates an existing memory's content, metadata, or container tags.
104

105
```typescript { .api }
106
/**
107
 * Update a memory with any content type (text, url, file, etc.) and metadata
108
 * @param id - Memory ID to update
109
 * @param params - Update parameters
110
 * @returns Promise resolving to update response
111
 */
112
update(id: string, params?: MemoryUpdateParams): APIPromise<MemoryUpdateResponse>;
113

114
interface MemoryUpdateParams {
115
  content?: string;
116
  customId?: string;
117
  metadata?: { [key: string]: string | number | boolean };
118
  containerTag?: string;
119
  /** @deprecated Use containerTag instead */
120
  containerTags?: string[];
121
}
122

123
interface MemoryUpdateResponse {
124
  id: string;
125
  status: string;
126
}
127
```
128

129
**Usage Example:**
130

131
```typescript
132
const updated = await client.memories.update("memory-id-123", {
133
  metadata: { category: "updated", priority: 2 },
134
  containerTag: "project_456",
135
});
136
```
137

138
### Delete Memory
139

140
Permanently removes a memory by ID.
141

142
```typescript { .api }
143
/**
144
 * Delete a memory by ID
145
 * @param id - Memory ID to delete
146
 * @returns Promise resolving to void
147
 */
148
delete(id: string): APIPromise<void>;
149
```
150

151
**Usage Example:**
152

153
```typescript
154
await client.memories.delete("memory-id-123");
155
```
156

157
### List Memories
158

159
Retrieves a paginated list of memories with filtering, sorting, and optional content inclusion.
160

161
```typescript { .api }
162
/**
163
 * Retrieves a paginated list of memories with their metadata and workflow status
164
 * @param params - List parameters for filtering and pagination
165
 * @returns Promise resolving to paginated memory list
166
 */
167
list(params?: MemoryListParams): APIPromise<MemoryListResponse>;
168

169
interface MemoryListParams {
170
  /** Container tags for filtering */
171
  containerTags?: string[];
172
  /** Filter expression for advanced filtering */
173
  filters?: string;
174
  /** Include full content in response (increases response size) */
175
  includeContent?: boolean;
176
  /** Items per page */
177
  limit?: string | number;
178
  /** Sort order */
179
  order?: "asc" | "desc";
180
  /** Page number */
181
  page?: string | number;
182
  /** Sort field */
183
  sort?: "createdAt" | "updatedAt";
184
}
185

186
interface MemoryListResponse {
187
  memories: Memory[];
188
  pagination: Pagination;
189
}
190

191
interface Memory {
192
  id: string;
193
  connectionId: string | null;
194
  createdAt: string;
195
  customId: string | null;
196
  metadata: string | number | boolean | { [key: string]: unknown } | Array<unknown> | null;
197
  status: MemoryStatus;
198
  summary: string | null;
199
  title: string | null;
200
  type: MemoryType;
201
  updatedAt: string;
202
  containerTags?: string[];
203
  content?: string; // Only included when includeContent=true
204
}
205

206
interface Pagination {
207
  currentPage: number;
208
  limit: number;
209
  totalItems: number;
210
  totalPages: number;
211
}
212
```
213

214
**Usage Examples:**
215

216
```typescript
217
// Basic listing
218
const memories = await client.memories.list({
219
  limit: 50,
220
  sort: "createdAt",
221
  order: "desc",
222
});
223

224
// Filtered listing with content
225
const filteredMemories = await client.memories.list({
226
  containerTags: ["user_123", "project_456"],
227
  includeContent: true,
228
  filters: "status:done",
229
});
230
```
231

232
### Upload File
233

234
Uploads a file to be processed as a memory with automatic content extraction.
235

236
```typescript { .api }
237
/**
238
 * Upload a file to be processed
239
 * @param params - File upload parameters
240
 * @returns Promise resolving to upload response
241
 */
242
uploadFile(params: MemoryUploadFileParams): APIPromise<MemoryUploadFileResponse>;
243

244
interface MemoryUploadFileParams {
245
  /** File to upload (supports multiple input types) */
246
  file: Uploadable;
247
  /** Container tags for the uploaded memory */
248
  containerTags?: string;
249
}
250

251
interface MemoryUploadFileResponse {
252
  id: string;
253
  status: string;
254
}
255
```
256

257
**Usage Examples:**
258

259
```typescript
260
import fs from "fs";
261
import { toFile } from "supermemory";
262

263
// Upload from filesystem
264
const fileMemory = await client.memories.uploadFile({
265
  file: fs.createReadStream("./document.pdf"),
266
  containerTags: "documents",
267
});
268

269
// Upload from Buffer
270
const bufferMemory = await client.memories.uploadFile({
271
  file: await toFile(Buffer.from("file content"), "document.txt"),
272
  containerTags: "text-files",
273
});
274

275
// Upload from web File API
276
const webFileMemory = await client.memories.uploadFile({
277
  file: new File(["content"], "document.txt"),
278
  containerTags: "uploads",
279
});
280
```
281

282
## Memory Types and Status
283

284
```typescript { .api }
285
type MemoryStatus = 
286
  | "unknown"     // Initial state
287
  | "queued"      // Waiting for processing
288
  | "extracting"  // Content extraction in progress
289
  | "chunking"    // Breaking content into chunks
290
  | "embedding"   // Generating embeddings
291
  | "indexing"    // Adding to search index
292
  | "done"        // Processing complete
293
  | "failed";     // Processing failed
294

295
type MemoryType = 
296
  | "text"         // Plain text content
297
  | "pdf"          // PDF document
298
  | "tweet"        // Twitter/X post
299
  | "google_doc"   // Google Docs document
300
  | "google_slide" // Google Slides presentation
301
  | "google_sheet" // Google Sheets spreadsheet
302
  | "image"        // Image file
303
  | "video"        // Video file
304
  | "notion_doc"   // Notion document
305
  | "webpage"      // Web page content
306
  | "onedrive";    // OneDrive document
307
```
308

309
## Error Handling
310

311
Memory operations can throw various errors:
312

313
```typescript
314
try {
315
  const memory = await client.memories.add({ content: "test" });
316
} catch (error) {
317
  if (error instanceof BadRequestError) {
318
    console.error("Invalid parameters:", error.message);
319
  } else if (error instanceof AuthenticationError) {
320
    console.error("Authentication failed:", error.message);
321
  } else if (error instanceof RateLimitError) {
322
    console.error("Rate limit exceeded:", error.message);
323
  }
324
}