# 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

```bash
# 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`)