mem0-local-hermes-plugin/README.md

# 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:
   ```bash
   docker run -d -p 8000:8000 mem0ai/mem0:latest
   ```

   Or via Docker Compose with custom config:
   ```yaml
   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**:
   ```bash
   curl http://localhost:8000/health
   ```

   Your setup uses port 8889:
   ```bash
   curl http://10.0.0.150:8889/health
   ```

## Installation

From Gitea repository:
```bash
hermes plugins install ARIA/mem0-local-hermes-plugin
```

Or with full URL:
```bash
hermes plugins install https://gitea.zephyre.one/ARIA/mem0-local-hermes-plugin.git
```

From local directory (during development):
```bash
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:
```bash
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` |

Example:
```env
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:
```json
{
  "base_url": "http://10.0.0.150:8889",
  "user_id": "henry_hofmann",
  "agent_id": "hermes",
  "rerank": true,
  "timeout": 10.0
}
```

Example for your setup:
```json
{
  "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

```bash
hermes memory mem0-local
```

### Restart Gateway

```bash
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:
```bash
hermes plugins install /path/to/mem0-local-hermes-plugin
```

Watch for changes:
```bash
# In plugin directory
hermes gateway restart  # After each change
```

## License

MIT