130 lines
5.4 KiB
Markdown
130 lines
5.4 KiB
Markdown
---
|
|
name: mem0-memory
|
|
description: "Use when configuring Mem0 as Hermes' memory provider."
|
|
version: 1.0.0
|
|
author: Hermes Agent
|
|
license: MIT
|
|
metadata:
|
|
hermes:
|
|
tags: [mem0, memory, qdrant, ollama, hermes, migration]
|
|
related_skills: [hermes-agent, holographic-memory, hermes-config-bulk-update]
|
|
---
|
|
|
|
# Mem0 Memory Provider for Hermes Agent
|
|
|
|
Mem0 is Hermes' server-side LLM fact-extraction memory provider with semantic
|
|
search and automatic deduplication. Plugin lives at
|
|
`~/.hermes/hermes-agent/plugins/memory/mem0/` (v1.3.0+). It is the sibling of
|
|
`holographic-memory` (local SQLite) — see that skill for the provider being
|
|
replaced in a migration.
|
|
|
|
## When to Use
|
|
|
|
- Setting up mem0 as the memory provider (any of its 3 modes)
|
|
- Migrating from holographic (or another provider) to mem0
|
|
- Troubleshooting mem0 OSS mode (Qdrant/embedder/LLM wiring)
|
|
- Understanding mem0's tools vs holographic's `fact_store`
|
|
|
|
## Three Connection Modes
|
|
|
|
| Mode | Trigger | Needs |
|
|
|------|---------|-------|
|
|
| **Platform** (cloud) | `MEM0_API_KEY` set | API key from app.mem0.ai |
|
|
| **Self-hosted server** | `host` set (Docker dashboard URL) | Mem0 server + optional `X-API-Key` |
|
|
| **OSS** (in-process) | `mode: oss` | own LLM + embedder + vector store |
|
|
|
|
Precedence in the plugin: **OSS > host > platform**. Setting `host` routes to
|
|
self-hosted HTTP; `mode: oss` overrides and ignores `host`.
|
|
|
|
## OSS Mode Config (mem0.json)
|
|
|
|
Config lives in `$HERMES_HOME/mem0.json` (per-profile). Only the secret
|
|
`MEM0_API_KEY` belongs in `.env`. Structure:
|
|
|
|
```json
|
|
{
|
|
"mode": "oss",
|
|
"oss": {
|
|
"llm": {"provider": "ollama", "config": {"model": "qwen3:8b", "ollama_base_url": "http://localhost:11434"}},
|
|
"embedder": {"provider": "ollama", "config": {"model": "snowflake-arctic-embed2:latest", "ollama_base_url": "http://10.0.0.30:11434", "embedding_dims": 1024}},
|
|
"vector_store": {"provider": "qdrant", "config": {"url": "http://10.0.0.161:6333", "collection_name": "mem0_general"}}
|
|
}
|
|
}
|
|
```
|
|
|
|
Supported OSS providers (from `_oss_providers.py`):
|
|
- LLM: `openai`, `ollama`
|
|
- Embedder: `openai`, `ollama`
|
|
- Vector store: `qdrant` (local `path` or server `url`), `pgvector`
|
|
|
|
## CRITICAL PITFALL — embedding_dims not auto-set
|
|
|
|
The plugin's `KNOWN_DIMS` map only lists `nomic-embed-text` (768) and OpenAI
|
|
models (`text-embedding-3-small` 1536, `-large` 3072, `ada-002` 1536). It does
|
|
**NOT** include `snowflake-arctic-embed2` (1024 dims).
|
|
|
|
Consequence: `hermes memory setup mem0 --mode oss` will NOT write
|
|
`embedding_dims` for snowflake-arctic-embed2, so mem0 creates the Qdrant
|
|
collection with wrong/unknown dims and writes fail.
|
|
|
|
Fix: set `embedding_dims` manually in `mem0.json` (or run setup then patch the
|
|
file). Verify the actual dims with:
|
|
```bash
|
|
curl -s http://<ollama-host>:11434/api/show -d '{"name":"snowflake-arctic-embed2:latest"}' \
|
|
| python3 -c "import sys,json; print(json.load(sys.stdin)['model_info']['bert.embedding_length'])"
|
|
```
|
|
The plugin's `_recreate_collection_if_dims_changed` will delete a stale
|
|
collection when dims change, so a wrong first attempt self-heals on the next
|
|
correct config — but only if `embedding_dims` is eventually set.
|
|
|
|
## Per-Profile Isolation on a Shared Qdrant
|
|
|
|
Holographic was per-profile (own `memory_store.db`). When all profiles point at
|
|
ONE shared Qdrant, the default collection name (`mem0`) would pool every
|
|
profile's memory together. Preserve isolation with per-profile
|
|
`collection_name` (e.g. `mem0_general`, `mem0_finance`, `mem0_base`).
|
|
|
|
## Tools (vs holographic)
|
|
|
|
| mem0 | holographic |
|
|
|------|-------------|
|
|
| `mem0_search` | `fact_store search` |
|
|
| `mem0_add` (verbatim, no extraction) | `fact_store add` |
|
|
| `mem0_update` | `fact_store update` |
|
|
| `mem0_delete` | `fact_store remove` |
|
|
|
|
No `fact_feedback` equivalent — mem0 has no trust scoring. `mem0_add` stores
|
|
verbatim; LLM extraction happens via `sync_turn`, not `mem0_add`.
|
|
|
|
## Migration Checklist (holographic → mem0)
|
|
|
|
1. Write per-profile `mem0.json` (OSS mode) with `embedding_dims` set manually.
|
|
2. `hermes config set memory.provider mem0` per profile (base + all profiles).
|
|
3. Remove holographic: delete plugin dir + all `memory_store.db` files + the
|
|
`plugins.hermes-memory-store` block (auto_extract/hrr_dim) from configs.
|
|
4. Update tool references: MEMORY.md rules and `save`/`cognee-brain` skills
|
|
reference `fact_store`/`fact_feedback` — they orphan on switch.
|
|
5. Smoke test ONE profile first: `mem0_add` → `mem0_search` → `mem0_delete`,
|
|
then confirm the Qdrant collection exists with correct dims before fanning out.
|
|
|
|
## Pitfalls
|
|
|
|
- **Network coupling.** mem0 OSS depends on the Qdrant host and embedder host
|
|
being reachable. Holographic was fully local (SQLite). If either service is
|
|
down, memory writes fail.
|
|
- **Circuit breaker.** "Mem0 temporarily unavailable" = 5 consecutive failures
|
|
tripped the breaker; resets after 2 minutes.
|
|
- **`mem0_add` is verbatim.** No LLM extraction on that path — use `sync_turn`
|
|
for extraction.
|
|
- **Cloud LLM fact-extraction quality varies.** Tested (2026-08): `kimi-k2.6:cloud`
|
|
and `minimax-m3:cloud` preserved full facts including temporal detail;
|
|
`deepseek-v4-pro:cloud` dropped "in March"; `glm-5.2:cloud` dropped both
|
|
"red" and "in March". For memory extraction, prefer a model that keeps
|
|
temporal context.
|
|
- **`gemini-3-flash-preview` retired 2026-07-15** — do not select it.
|
|
|
|
## References
|
|
|
|
- `references/oss-config-and-dims.md` — full OSS config schema, KNOWN_DIMS map,
|
|
and the embedding-dims gotcha with verification commands.
|