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
   ```

   Adjust the URL/port as needed for your setup.

## 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` |
| `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:
   ```env
   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:
```json
{
  "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

```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) |
| `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:
```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