mem0-mcp-selfhosted: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code when working with code in this repository.

MCP Servers

• mem0: Persistent memory across sessions. At the start of each session, search_memories for relevant context before asking the user to re-explain anything. Use add_memory whenever you discover project architecture, coding conventions, debugging insights, key decisions, or user preferences. Use update_memory when prior context changes. Save information like: "This project uses PostgreSQL with Prisma", "Tests run with pytest -v", "Auth uses JWT validated in middleware". When in doubt, save it — future sessions benefit from over-remembering.

Build & Test Commands

pip install -e ".[dev]"              # Install with dev dependencies
python3 -m pytest tests/unit/ -v     # Unit tests (mocked, no infra needed)
python3 -m pytest tests/contract/ -v # Contract tests (validates mem0ai internals)
python3 -m pytest tests/integration/ -v  # Integration tests (requires live Qdrant + Neo4j + Ollama)
python3 -m pytest tests/ -v          # All tests
python3 -m pytest tests/ -m "not integration" -v  # Skip integration
python3 -m pytest tests/unit/test_auth.py::TestIsOatToken -v  # Single test class
python3 -m pytest tests/unit/test_auth.py::TestIsOatToken::test_oat_token_detected -v  # Single test

Architecture

Self-hosted MCP server using mem0ai as a library. 11 tools (9 memory + 2 graph), FastMCP orchestrator.

Module roles:

• server.py — FastMCP orchestrator, registers all tools + memory_assistant prompt
• config.py — Env vars → mem0ai MemoryConfig dict, handles all 5 graph LLM provider configs
• auth.py — 3-tier token fallback: MEM0_ANTHROPIC_TOKEN → ~/.claude/.credentials.json → ANTHROPIC_API_KEY
• llm_anthropic.py — Custom Anthropic provider registered with mem0ai's LlmFactory; handles OAT headers, structured outputs (JSON schema via output_config), and tool-call parsing
• llm_router.py — SplitModelGraphLLM routes by tool name: extraction tools → Gemini, contradiction tools → Claude
• helpers.py — _mem0_call() error wrapper, call_with_graph() threading lock for per-call graph toggle, safe_bulk_delete() iterates+deletes individually (never calls memory.delete_all()), patch_graph_sanitizer() monkey-patches mem0ai's relationship sanitizer for Neo4j compliance
• graph_tools.py — Direct Neo4j Cypher queries with lazy driver init
• __init__.py — Suppresses mem0ai telemetry before any imports