Files
waggle-os/docs/oss/research/mem0-3.3.1.md
shumeiko.it 10ad678547 docs(oss): record the memory contract decision (ADR-0007)
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).
2026-10-18 14:28:13 +02:00

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.