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).
3.8 KiB
3.8 KiB
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 viabetter-sqlite3atvectorStore.config.dbPath, tablevectors(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
sqliteathistoryDbPath. - 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. Thelangchainprovider accepts any object withembedQuery(text)andembedDocuments(texts)(duck-typed, no LangChain import), so Waggle's in-process embedder can be passed in directly. - LLMs:
openai(acceptsbaseURLandapiKey, sendsresponse_format),anthropic,ollama,litellm,groq,mistral,google,deepseek,xai,vllm,lmstudio, and others. ThelangchainLLM provider imports@langchain/coreat runtime, so we do not use it. Pointing theopenaiprovider 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_allandresetsends an event to mem0's PostHog project (https://us.i.posthog.com, line 14821). It is read once at module load fromMEM0_TELEMETRY(line 14817). SetMEM0_TELEMETRY=falsebefore the module is imported, which means importingmem0ai/ossdynamically after setting the variable. With telemetry on, mem0 also downloads a notice configuration fromraw.githubusercontent.com(observed on 2026-10-18 with a stubbedfetch); both stop when telemetry is off. - Home directory. mem0 reads and writes
~/.mem0/config.jsonunlessMEM0_DIRis set (lines 15056, 16962). PointMEM0_DIRinto the Waggle data directory. - Console notices (first run, decay, scale thresholds) are printed by default.