184 lines
7.6 KiB
Markdown
184 lines
7.6 KiB
Markdown
# Mem0 TypeScript SDK
|
|
|
|
[](https://www.npmjs.com/package/mem0ai)
|
|
[](https://github.com/mem0ai/mem0/blob/main/LICENSE)
|
|
|
|
Mem0 gives AI assistants and agents persistent memory. It extracts useful facts from conversations, scopes them to a user, agent, or run, and retrieves the relevant facts for later interactions. The `mem0ai` package includes `MemoryClient` for the hosted Mem0 Platform and `Memory` for open-source, in-process memory.
|
|
|
|
## Requirements
|
|
|
|
- Hosted `MemoryClient`: Node.js 18 or later and `MEM0_API_KEY` from the [Mem0 dashboard](https://app.mem0.ai/dashboard/api-keys)
|
|
- Open-source `Memory` with the default storage: Node.js 20 or later because `better-sqlite3` v12 requires Node 20+
|
|
- Open source with the default providers: `OPENAI_API_KEY`
|
|
|
|
## Install
|
|
|
|
```bash
|
|
npm install mem0ai
|
|
```
|
|
|
|
## Platform or open source
|
|
|
|
| | Platform (`MemoryClient`) | Open source (`Memory`) |
|
|
| ------------------- | --------------------------------------- | --------------------------------------------------------------------- |
|
|
| Import | `import { MemoryClient } from "mem0ai"` | `import { Memory } from "mem0ai/oss"` |
|
|
| Where memories live | Mem0's hosted API | Your configured vector store |
|
|
| Required key | `MEM0_API_KEY` | `OPENAI_API_KEY` with the defaults, or keys for your chosen providers |
|
|
| Extraction | Managed and asynchronous | Runs against your configured LLM |
|
|
| Best for | Zero-ops production use | Local development and custom infrastructure |
|
|
|
|
## Platform quickstart
|
|
|
|
Set `MEM0_API_KEY`, then add a conversation:
|
|
|
|
```ts
|
|
import { MemoryClient, type Message } from "mem0ai";
|
|
|
|
const client = new MemoryClient({ apiKey: process.env.MEM0_API_KEY! });
|
|
|
|
const messages: Message[] = [
|
|
{ role: "user", content: "I am vegetarian and allergic to nuts." },
|
|
{ role: "assistant", content: "I will remember that." },
|
|
];
|
|
await client.add(messages, { userId: "alex" });
|
|
```
|
|
|
|
Hosted `add()` queues extraction and usually returns an `eventId` with `status: "PENDING"`. Do not search immediately after `add()`. Wait for processing to finish in the dashboard, or use a [`memory_add` webhook](https://docs.mem0.ai/platform/features/webhooks), then search:
|
|
|
|
```ts
|
|
import { MemoryClient } from "mem0ai";
|
|
|
|
const client = new MemoryClient({ apiKey: process.env.MEM0_API_KEY! });
|
|
const results = await client.search("What does Alex eat?", {
|
|
filters: { user_id: "alex" },
|
|
topK: 5,
|
|
});
|
|
console.log(results.results);
|
|
```
|
|
|
|
`search()` and `getAll()` take entity IDs inside `filters` with snake_case keys. `add()` and `deleteAll()` take `userId`, `agentId`, or `runId` as top-level camelCase options.
|
|
|
|
## Open-source quickstart
|
|
|
|
Set `OPENAI_API_KEY` before using the default OpenAI LLM and embedder:
|
|
|
|
```ts
|
|
import { Memory } from "mem0ai/oss";
|
|
|
|
const memory = new Memory();
|
|
|
|
const messages = [
|
|
{ role: "user", content: "I am vegetarian and allergic to nuts." },
|
|
{ role: "assistant", content: "I will remember that." },
|
|
];
|
|
await memory.add(messages, { userId: "alex" });
|
|
|
|
const results = await memory.search("What does Alex eat?", {
|
|
filters: { user_id: "alex" },
|
|
topK: 5,
|
|
});
|
|
console.log(results.results);
|
|
```
|
|
|
|
The default `Memory` configuration uses OpenAI `gpt-5-mini`, OpenAI `text-embedding-3-small`, a SQLite-backed vector store at `~/.mem0/vector_store.db`, and a SQLite history database at `memory.db`.
|
|
|
|
## Configuration and features
|
|
|
|
Pass a config object to `Memory` to change providers or storage:
|
|
|
|
```ts
|
|
import { Memory } from "mem0ai/oss";
|
|
|
|
const memory = new Memory({
|
|
llm: {
|
|
provider: "anthropic",
|
|
config: {
|
|
apiKey: process.env.ANTHROPIC_API_KEY,
|
|
model: "claude-sonnet-4-5",
|
|
},
|
|
},
|
|
embedder: {
|
|
provider: "openai",
|
|
config: {
|
|
apiKey: process.env.OPENAI_API_KEY,
|
|
model: "text-embedding-3-small",
|
|
},
|
|
},
|
|
vectorStore: {
|
|
provider: "qdrant",
|
|
config: {
|
|
collectionName: "memories",
|
|
host: "localhost",
|
|
port: 6333,
|
|
dimension: 1536,
|
|
},
|
|
},
|
|
});
|
|
```
|
|
|
|
Provider integrations use a mix of bundled dependencies and peer dependencies. OpenAI is bundled. Most provider peers are optional, but `package.json` also declares required peers such as `better-sqlite3`, `pg`, `compromise`, and `natural`. Install the SDK for any optional provider you configure.
|
|
|
|
### Memory operations
|
|
|
|
Both clients expose asynchronous memory operations. The open-source methods finish their work before resolving. Hosted `add()` only confirms that the extraction job was queued.
|
|
|
|
| Operation | Platform | Open source |
|
|
| ---------------------- | ----------------------------------- | ----------------------------------- |
|
|
| Add | `client.add(messages, { userId })` | `memory.add(messages, { userId })` |
|
|
| Search | `client.search(query, { filters })` | `memory.search(query, { filters })` |
|
|
| List | `client.getAll({ filters })` | `memory.getAll({ filters })` |
|
|
| Get | `client.get(memoryId)` | `memory.get(memoryId)` |
|
|
| Update | `client.update(memoryId, { text })` | `memory.update(memoryId, { text })` |
|
|
| Delete | `client.delete(memoryId)` | `memory.delete(memoryId)` |
|
|
| Delete scoped memories | `client.deleteAll({ userId })` | `memory.deleteAll({ userId })` |
|
|
| History | `client.history(memoryId)` | `memory.history(memoryId)` |
|
|
|
|
### Filters
|
|
|
|
Use snake_case keys inside `filters`. A flat object combines conditions with AND. Use `AND`, `OR`, or `NOT` for explicit grouping:
|
|
|
|
```ts
|
|
const filters = {
|
|
AND: [{ user_id: "alex" }, { categories: { contains: "food" } }],
|
|
};
|
|
```
|
|
|
|
Pass this object as `filters` to `search()` or `getAll()`.
|
|
|
|
Comparison operators include `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `contains`, and `icontains`. Open-source `Memory` also supports `nin`. See [memory filters](https://docs.mem0.ai/platform/features/v2-memory-filters).
|
|
|
|
### Platform features
|
|
|
|
`MemoryClient` also supports users, batch operations, project settings, webhooks, feedback, and memory exports. See the [Platform API reference](https://docs.mem0.ai/api-reference).
|
|
|
|
### Open-source providers
|
|
|
|
The TypeScript SDK supports configurable LLMs, embedders, vector stores, history stores, and rerankers. See the [Node quickstart](https://docs.mem0.ai/open-source/node-quickstart) and [component documentation](https://docs.mem0.ai/components/llms/overview) for supported provider names and configuration.
|
|
|
|
### CLI and integrations
|
|
|
|
Use the Node CLI to manage hosted memories from your terminal:
|
|
|
|
```bash
|
|
npm install -g @mem0/cli
|
|
```
|
|
|
|
See the [CLI reference](https://docs.mem0.ai/platform/cli) and [Vercel AI SDK integration](https://docs.mem0.ai/integrations/vercel-ai-sdk).
|
|
|
|
## Documentation and help
|
|
|
|
- [Node quickstart](https://docs.mem0.ai/open-source/node-quickstart)
|
|
- [Platform quickstart](https://docs.mem0.ai/platform/quickstart)
|
|
- [API reference](https://docs.mem0.ai/api-reference)
|
|
- [Discord](https://mem0.dev/DiG)
|
|
- [GitHub issues](https://github.com/mem0ai/mem0/issues)
|
|
- Email: founders@mem0.ai
|
|
|
|
## Contributing
|
|
|
|
Read [CONTRIBUTING.md](../CONTRIBUTING.md) before opening an issue or pull request.
|
|
|
|
## License
|
|
|
|
Apache 2.0. See [LICENSE](../LICENSE).
|