0
# Supermemory
1
2
Supermemory is the official TypeScript library for the Supermemory API, providing comprehensive memory management, search functionality, organization settings, and third-party integrations. Built with Stainless from OpenAPI specifications, it offers a modern, type-safe client for interacting with the Supermemory REST API.
3
4
## Package Information
5
6
- **Package Name**: supermemory
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install supermemory`
10
11
## Core Imports
12
13
```typescript
14
import Supermemory from "supermemory";
15
```
16
17
For CommonJS:
18
19
```javascript
20
const Supermemory = require("supermemory");
21
```
22
23
Named imports for utilities:
24
25
```typescript
26
import { toFile, APIError, APIPromise } from "supermemory";
27
```
28
29
## Basic Usage
30
31
```typescript
32
import Supermemory from "supermemory";
33
34
const client = new Supermemory({
35
apiKey: process.env.SUPERMEMORY_API_KEY, // or provide directly
36
});
37
38
// Add a memory
39
const memory = await client.memories.add({
40
content: "Machine learning fundamentals",
41
metadata: { category: "education", topic: "ai" },
42
});
43
44
// Search memories
45
const results = await client.search.documents({
46
q: "machine learning concepts",
47
limit: 10,
48
});
49
50
// Get organization settings
51
const settings = await client.settings.get();
52
```
53
54
## Architecture
55
56
Supermemory is organized around four main resource groups:
57
58
- **Client Core**: Main Supermemory class with authentication, configuration, and HTTP methods
59
- **Memory Management**: Create, read, update, delete memories with rich metadata and file upload support
60
- **Search Engine**: Advanced semantic search across documents and memories with filtering and ranking
61
- **Settings Management**: Organization-level configuration for integrations and filtering
62
- **Connection Management**: Third-party service integrations (Notion, Google Drive, OneDrive)
63
64
The library provides comprehensive error handling, automatic retries with exponential backoff, request/response logging, and enhanced Promise objects with raw response access.
65
66
## Capabilities
67
68
### Client Configuration
69
70
Core client instantiation and configuration options for authentication, timeouts, and customization.
71
72
```typescript { .api }
73
class Supermemory {
74
constructor(options?: ClientOptions);
75
withOptions(options: Partial<ClientOptions>): Supermemory;
76
}
77
78
interface ClientOptions {
79
apiKey?: string;
80
baseURL?: string;
81
timeout?: number;
82
maxRetries?: number;
83
logLevel?: LogLevel;
84
logger?: Logger;
85
fetchOptions?: RequestInit;
86
fetch?: Fetch;
87
defaultHeaders?: HeadersLike;
88
defaultQuery?: Record<string, string | undefined>;
89
}
90
```
91
92
### Memory Management
93
94
Comprehensive memory operations including creation, retrieval, updates, deletion, and file uploads.
95
96
```typescript { .api }
97
interface Memories {
98
add(params?: MemoryAddParams): APIPromise<MemoryAddResponse>;
99
get(id: string): APIPromise<MemoryGetResponse>;
100
update(id: string, params?: MemoryUpdateParams): APIPromise<MemoryUpdateResponse>;
101
delete(id: string): APIPromise<void>;
102
list(params?: MemoryListParams): APIPromise<MemoryListResponse>;
103
uploadFile(params: MemoryUploadFileParams): APIPromise<MemoryUploadFileResponse>;
104
}
105
```
106
107
[Memory Management](./memories.md)
108
109
### Search Operations
110
111
Advanced search functionality for finding memories and documents with semantic understanding and filtering.
112
113
```typescript { .api }
114
interface Search {
115
documents(params: SearchDocumentsParams): APIPromise<SearchDocumentsResponse>;
116
execute(params: SearchExecuteParams): APIPromise<SearchExecuteResponse>;
117
memories(params: SearchMemoriesParams): APIPromise<SearchMemoriesResponse>;
118
}
119
```
120
121
[Search Operations](./search.md)
122
123
### Settings Management
124
125
Organization-level settings configuration for integrations, filtering, and customization.
126
127
```typescript { .api }
128
interface Settings {
129
get(): APIPromise<SettingGetResponse>;
130
update(params?: SettingUpdateParams): APIPromise<SettingUpdateResponse>;
131
}
132
```
133
134
[Settings Management](./settings.md)
135
136
### Connection Management
137
138
Third-party service integrations for automated content synchronization and document importing.
139
140
```typescript { .api }
141
interface Connections {
142
create(provider: ConnectionProvider, params?: ConnectionCreateParams): APIPromise<ConnectionCreateResponse>;
143
list(params?: ConnectionListParams): APIPromise<ConnectionListResponse>;
144
getByID(connectionID: string): APIPromise<ConnectionGetByIDResponse>;
145
getByTags(provider: ConnectionProvider, params: ConnectionGetByTagsParams): APIPromise<ConnectionGetByTagsResponse>;
146
deleteByID(connectionID: string): APIPromise<ConnectionDeleteByIDResponse>;
147
deleteByProvider(provider: ConnectionProvider, params: ConnectionDeleteByProviderParams): APIPromise<ConnectionDeleteByProviderResponse>;
148
import(provider: ConnectionProvider, params?: ConnectionImportParams): APIPromise<string>;
149
listDocuments(provider: ConnectionProvider, params?: ConnectionListDocumentsParams): APIPromise<ConnectionListDocumentsResponse>;
150
}
151
```
152
153
[Connection Management](./connections.md)
154
155
## Core Types
156
157
```typescript { .api }
158
type LogLevel = "debug" | "info" | "warn" | "error" | "off";
159
160
type ConnectionProvider = "notion" | "google-drive" | "onedrive";
161
162
type MemoryStatus = "unknown" | "queued" | "extracting" | "chunking" | "embedding" | "indexing" | "done" | "failed";
163
164
type MemoryType = "text" | "pdf" | "tweet" | "google_doc" | "google_slide" | "google_sheet" | "image" | "video" | "notion_doc" | "webpage" | "onedrive";
165
166
interface APIPromise<T> extends Promise<T> {
167
asResponse(): Promise<Response>;
168
withResponse(): Promise<{ data: T; response: Response }>;
169
}
170
171
interface RequestOptions {
172
timeout?: number;
173
maxRetries?: number;
174
headers?: HeadersLike;
175
query?: Record<string, unknown>;
176
fetchOptions?: RequestInit;
177
signal?: AbortSignal;
178
idempotencyKey?: string;
179
}
180
```
181
182
## Error Handling
183
184
```typescript { .api }
185
class SupermemoryError extends Error {}
186
187
class APIError extends SupermemoryError {
188
readonly status: number;
189
readonly headers: Headers;
190
readonly error: object;
191
}
192
193
class APIConnectionError extends APIError {}
194
class APIConnectionTimeoutError extends APIConnectionError {}
195
class APIUserAbortError extends APIError {}
196
class BadRequestError extends APIError {} // 400
197
class AuthenticationError extends APIError {} // 401
198
class PermissionDeniedError extends APIError {} // 403
199
class NotFoundError extends APIError {} // 404
200
class ConflictError extends APIError {} // 409
201
class UnprocessableEntityError extends APIError {} // 422
202
class RateLimitError extends APIError {} // 429
203
class InternalServerError extends APIError {} // 5xx
204
```
205
206
## File Upload Utilities
207
208
```typescript { .api }
209
type Uploadable = File | Response | ReadStream | Buffer | Uint8Array | ArrayBuffer | DataView | FormData | URLSearchParams;
210
211
/**
212
* Converts various input types to uploadable file format
213
* @param value - Input data (Buffer, Uint8Array, etc.) or PromiseLike
214
* @param name - Optional filename for the upload
215
* @param options - Optional FilePropertyBag with properties like lastModified
216
* @returns Promise resolving to File object
217
*/
218
function toFile(
219
value: ToFileInput | PromiseLike<ToFileInput>,
220
name?: string | null,
221
options?: FilePropertyBag
222
): Promise<File>;
223
224
type ToFileInput =
225
| FileLike // File-like objects with name, lastModified properties
226
| ResponseLike // Response objects with url and blob() method
227
| BlobLikePart // string | ArrayBuffer | ArrayBufferView | BlobLike | DataView
228
| AsyncIterable<BlobLikePart>;
229
```