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
• Same-turn prefetch — Memory retrieved synchronously before the LLM call (~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
   

   Adjust the URL/port as needed for your setup.

Installation

From Gitea repository:

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

Or with full URL:

hermes plugins install https://gitea.zephyre.one/ARIA/mem0-local-hermes-plugin.git

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)

Troubleshooting

"PluginContext has no attribute 'register_memory_provider'"

This plugin supports both memory provider and general plugin contexts. If you see this error, ensure you're using version 1.0.0 or later, which includes automatic fallback to tool registration.

To reinstall:

hermes plugins uninstall mem0-local
hermes plugins install ARIA/mem0-local-hermes-plugin

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
MEM0_PREFETCH_LIMIT	Max memories to prefetch before LLM call	3
MEM0_PREFETCH_SCORE_THRESHOLD	Min similarity score % to include memory (0-100)	60

Example:

MEM0_BASE_URL=http://localhost:8000
MEM0_USER_ID=my-user
MEM0_AGENT_ID=hermes
MEM0_PREFETCH_LIMIT=3
MEM0_PREFETCH_SCORE_THRESHOLD=60

Method 2: Config File (Optional Overrides)

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

{
  "base_url": "http://localhost:8000",
  "user_id": "my-user",
  "agent_id": "hermes",
  "rerank": true,
  "timeout": 10.0,
  "prefetch_limit": 3,
  "prefetch_score_threshold": 60
}

Usage

Activate the Memory Provider

hermes memory mem0-local

Restart Gateway

hermes gateway restart

How It Works

1. User message received → prefetch() searches Mem0 synchronously (~40ms)
2. Context injection → Results injected before the LLM call
3. LLM receives → User message + memory context (no tool call needed!)

Example:

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

↓ [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)
mem0_delete	Delete a specific memory by ID. Use when user explicitly requests to remove or forget a stored fact.

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:

• 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