hermes-skills/mem0-memory/SKILL.md

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