Mem0 Local Hermes Plugin

Self-hosted Mem0 memory provider for Hermes-Agent. Provides semantic memory search, automatic fact extraction, and context injection without tool calls.

Features

• Local Mem0 server — No cloud dependency, full data privacy
• Async prefetch — Memory retrieval happens in background (~40ms)
• Context injection — Relevant memories injected directly into LLM prompt
• Automatic fact extraction — Server-side LLM extracts facts from conversations
• Semantic search — Find memories by meaning, not keywords
• Circuit breaker — Automatic failover on server unavailability

Prerequisites

1. Mem0 server running locally:

   Using Docker:

   docker run -d -p 8000:8000 mem0ai/mem0:latest
   

   Or via Docker Compose with custom config:

   version: "3.8"
   services:
     mem0:
       image: mem0ai/mem0:latest
       ports:
         - "8000:8000"
       environment:
         - MEM0_CONFIG_PATH=/app/config.yaml
       volumes:
         - ./mem0-config.yaml:/app/config.yaml
         - mem0_data:/app/data
   volumes:
     mem0_data:
   

2. Verify server is reachable:

   curl http://localhost:8000/health
   

   Your setup uses port 8889:

   curl http://10.0.0.150:8889/health
   

Installation

From GitHub repository:

hermes plugins install https://github.com/yourusername/mem0-local-hermes-plugin.git

Or with shorthand:

hermes plugins install yourusername/mem0-local-hermes-plugin

From local directory (during development):

hermes plugins install /path/to/mem0-local-hermes-plugin

The installer will prompt for:

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

Configuration

The plugin supports two configuration methods that work together:

1. Environment variables (~/.hermes/.env) - Primary configuration
2. Config file (~/.hermes/mem0-local.json) - Optional overrides

Precedence: Config file values override environment variables. This allows you to set defaults in .env and override specific values in the JSON file.

Method 1: Environment Variables (Recommended)

Set in ~/.hermes/.env:

Variable	Description	Default
MEM0_BASE_URL	Local Mem0 server URL	http://localhost:8000
MEM0_USER_ID	User identifier	hermes-user
MEM0_AGENT_ID	Agent identifier	hermes

Example:

MEM0_BASE_URL=http://10.0.0.150:8889
MEM0_USER_ID=henry_hofmann
MEM0_AGENT_ID=hermes

Method 2: Config File (Optional Overrides)

Create ~/.hermes/mem0-local.json to override specific settings:

{
  "base_url": "http://10.0.0.150:8889",
  "user_id": "henry_hofmann",
  "agent_id": "hermes",
  "rerank": true,
  "timeout": 10.0
}

Example for your setup:

{
  "base_url": "http://10.0.0.150:8889",
  "user_id": "henry_hofmann",
  "agent_id": "hermes",
  "rerank": true,
  "timeout": 10.0
}

Usage

Activate the Memory Provider

hermes memory mem0-local

Restart Gateway

hermes gateway restart

How It Works

1. User message received → queue_prefetch() spawns background thread
2. Mem0 search → Semantic search for relevant memories (~40ms)
3. Context injection → Results injected via pre_llm_call hook
4. LLM receives → User message + memory context (no tool call needed!)

Example:

User: "Hey, is a new episode out from my favorite anime?"

↓ [Background: mem0.prefetch() searches for "favorite anime"]

LLM receives:
"""
Hey, is a new episode out from my favorite anime?

## Mem0 Memory
- My favorite animes are Naruto, One Piece, and Demon Slayer (score: 0.87)
"""

Assistant: "Let me check for new episodes of Naruto, One Piece, and Demon Slayer..."

Available Tools

The plugin also provides explicit memory tools:

Tool	Description
mem0_profile	Retrieve all stored memories about the user
mem0_search	Search memories by semantic similarity
mem0_conclude	Store a fact verbatim (no LLM extraction)

Tool usage examples:

# Get all memories
mem0_profile()

# Search with reranking
mem0_search(query="project deadlines", rerank=true, top_k=5)

# Store a fact explicitly
mem0_conclude(conclusion="I prefer Python over JavaScript for backend development")

Circuit Breaker

After 5 consecutive API failures, the plugin pauses requests for 120 seconds to avoid hammering a down server. The breaker resets automatically.

Troubleshooting

"Mem0 server temporarily unavailable"

• Check server is running: curl http://your-server:port/health
• Verify MEM0_BASE_URL is correct
• Wait 2 minutes for circuit breaker to reset

"No memories stored yet"

• Mem0 extracts facts automatically from conversations
• Or use mem0_conclude to store facts explicitly

Memory not injected

• Check is_available() returns True in logs
• Verify prefetch() is being called (debug logs)
• Ensure Mem0 server has indexed memories
• Check network connectivity to your local server

Connection issues

If your Mem0 server is on a different machine (like your 10.0.0.150):

• Ensure firewall allows connections on port 8889
• Verify the server binds to 0.0.0.0, not just localhost
• Check network routing between Hermes-Agent and Mem0 server

Differences from Cloud Version

Aspect	Cloud Version	Local Version
Client	mem0.MemoryClient(api_key=...)	HTTP requests to local server
Auth	API key	None (local network)
Config	MEM0_API_KEY	MEM0_BASE_URL
Latency	Network-dependent	~40ms (local)
Privacy	Cloud processing	Full local control
Cost	Pay-per-use	Free (self-hosted)

Development

For development, install from local path:

hermes plugins install /path/to/mem0-local-hermes-plugin

Watch for changes:

# In plugin directory
hermes gateway restart  # After each change

License

MIT