ADR-0007 maps today's memory usage onto the contract and mem0: profile card and tasks move to waggle.db, learned facts stay in mem0, extraction runs in the background in batches. Research notes cover what mem0 3.3.1 does and how 68 files use memory today. Two defects found on the way are logged for the main project (UF-025, UF-026).
62 lines
3.8 KiB
Markdown
62 lines
3.8 KiB
Markdown
# mem0ai 3.3.1 (OSS build): what it does and what we must configure
|
|
|
|
Source: the published npm package `mem0ai@3.3.1`, entry `mem0ai/oss` (`dist/oss/index.d.ts`
|
|
and `dist/oss/index.js`), read on 2026-10-16. Line numbers refer to `dist/oss/index.js`.
|
|
|
|
## Package
|
|
|
|
- License Apache-2.0. Runtime dependencies: `zod`, `uuid`, `axios`, `openai`.
|
|
- 41 peer dependencies, 38 of them optional. The three required peers are `better-sqlite3`
|
|
(already in Waggle), `compromise` (MIT, NLP) and `@cloudflare/workers-types` (types only,
|
|
MIT OR Apache-2.0). npm installs required peers automatically.
|
|
|
|
## API (`class Memory`)
|
|
|
|
| Method | Signature | Notes |
|
|
|---|---|---|
|
|
| `add` | `add(messages: string \| Message[], { userId?, agentId?, runId?, metadata?, infer?, timestamp?, expirationDate? })` | `infer: true` (default) asks the LLM to extract facts and decide add/update/delete against existing memories in the same `userId`/`agentId`/`runId` scope |
|
|
| `search` | `search(query, { topK?, filters?, threshold?, rerank?, showExpired? })` | `filters` holds `user_id`/`agent_id`/`run_id` and any metadata key, with operators `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`, `contains`, `icontains` |
|
|
| `get` | `get(memoryId)` | `MemoryItem \| null` |
|
|
| `getAll` | `getAll({ topK?, filters?, showExpired? })` | listing per scope |
|
|
| `update` | `update(memoryId, { text?, metadata?, expirationDate? })` | |
|
|
| `delete` / `deleteAll` | `delete(memoryId)`, `deleteAll({ userId?, agentId?, runId? })` | |
|
|
| `history` | `history(memoryId)` | change log from the history store |
|
|
| `reset` | `reset()` | drops everything |
|
|
|
|
`MemoryItem` is `{ id, memory, hash?, createdAt?, updatedAt?, score?, rerankScore?, metadata? }`.
|
|
There is no graph memory in the OSS build.
|
|
|
|
## Storage
|
|
|
|
- Vector store `memory` (`MemoryVectorStore`, line 896): a SQLite file via `better-sqlite3` at
|
|
`vectorStore.config.dbPath`, table `vectors(id, vector BLOB, payload TEXT)`. Search loads the
|
|
rows matching the filters and ranks them by cosine similarity in JS. Fine for personal scale.
|
|
- History store `sqlite` at `historyDbPath`.
|
|
- Default paths fall back to the working directory or `~/.mem0`; always set them explicitly.
|
|
|
|
## Model providers
|
|
|
|
- Embedders: `openai`, `ollama`, `lmstudio`, `huggingface` (an HTTP TEI endpoint, not
|
|
in-process), `fastembed`, `google`, `azure_openai`, `vertexai`, `aws_bedrock`, `together`,
|
|
`langchain`. The `langchain` provider accepts any object with `embedQuery(text)` and
|
|
`embedDocuments(texts)` (duck-typed, no LangChain import), so Waggle's in-process embedder can
|
|
be passed in directly.
|
|
- LLMs: `openai` (accepts `baseURL` and `apiKey`, sends `response_format`), `anthropic`, `ollama`,
|
|
`litellm`, `groq`, `mistral`, `google`, `deepseek`, `xai`, `vllm`, `lmstudio`, and others. The
|
|
`langchain` LLM provider imports `@langchain/core` at runtime, so we do not use it. Pointing the
|
|
`openai` provider at the sidecar's built-in proxy (`http://127.0.0.1:<port>/v1`, session token
|
|
as key) reuses whatever model the user configured.
|
|
|
|
## Must-configure settings
|
|
|
|
- **Telemetry is on by default.** Every `add`, `search`, `update`, `delete`, `get_all` and `reset`
|
|
sends an event to mem0's PostHog project (`https://us.i.posthog.com`, line 14821). It is read
|
|
once at module load from `MEM0_TELEMETRY` (line 14817). Set `MEM0_TELEMETRY=false` before the
|
|
module is imported, which means importing `mem0ai/oss` dynamically after setting the variable.
|
|
With telemetry on, mem0 also downloads a notice configuration from
|
|
`raw.githubusercontent.com` (observed on 2026-10-18 with a stubbed `fetch`); both stop when
|
|
telemetry is off.
|
|
- **Home directory.** mem0 reads and writes `~/.mem0/config.json` unless `MEM0_DIR` is set
|
|
(lines 15056, 16962). Point `MEM0_DIR` into the Waggle data directory.
|
|
- Console notices (first run, decay, scale thresholds) are printed by default.
|