mem0-local-hermes-plugin/AGENTS.md

AGENTS.md — Mem0 Local Hermes Plugin

Structure

Single-file plugin: __init__.py contains the Mem0LocalMemoryProvider class. HTTP client in client.py. Manifest in plugin.yaml.

Key Commands

# Install from repo
hermes plugins install ARIA/mem0-local-hermes-plugin

# Install from local path (development)
hermes plugins install /path/to/mem0-local-hermes-plugin

# Activate memory provider
hermes memory mem0-local

# Restart gateway after changes
hermes gateway restart

# Verify Mem0 server
curl http://localhost:8000/health

Configuration

Two-tier config (JSON overrides env):

1. ~/.hermes/.env — Primary config
2. ~/.hermes/mem0-local.json — Optional overrides

Required env vars:

• MEM0_BASE_URL — Mem0 server URL (default: http://localhost:8000)
• MEM0_USER_ID — User identifier (default: hermes-user)

Optional env vars:

• MEM0_AGENT_ID — Agent identifier (default: hermes)
• MEM0_PREFETCH_LIMIT — Max memories to prefetch (default: 3)
• MEM0_PREFETCH_SCORE_THRESHOLD — Min similarity % (default: 60)

Architecture

Memory injection flow:

1. queue_prefetch() — Spawns background thread on user message
2. prefetch() — Returns cached result next turn
3. pre_llm_call hook — Sync prefetch for immediate injection (fallback context)
4. sync_turn() — Non-blocking server-side fact extraction

Circuit breaker: 5 consecutive failures → 120s cooldown.

Dual-context registration:

• register_memory_provider() — When installed in plugins/memory/
• register_tool() + pre_llm_call hook — When installed in ~/.hermes/plugins/

Tools

Tool	Purpose
mem0_profile	Get all stored memories
mem0_search	Semantic search with optional reranking
mem0_conclude	Store fact verbatim
mem0_delete	Delete memory by ID

Dependencies

• requests (via pip_dependencies in plugin.yaml)
• Hermes gateway with memory provider support
• Self-hosted Mem0 server (Docker image: mem0ai/mem0:latest)