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

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 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.