# Coppermind Memory Provider for Hermes Agent

This is a Hermes-specific memory provider that integrates Coppermind (SurrealDB-backed persistent memory) using the official MemoryProvider ABC.

## Features

- Automatic memory injection via `prefetch()` based on user queries
- Conversation turn ingestion via `sync_turn()`
- Session summary storage on session end
- Query truncation to prevent 431 errors (configurable)
- Clean separation from other frameworks (Codex, OpenClaw)

## Requirements

- A running Coppermind server (default: `http://127.0.0.1:18989`)
- Environment variables set in `~/.hermes/.env`:

```bash
COPPERMIND_BASE_URL=http://127.0.0.1:18989
COPPERMIND_USER_ID=default
COPPERMIND_TIMEOUT=10
COPPERMIND_MAX_QUERY_LENGTH=2000
```

## Activation

1. Ensure the provider is present in `~/.hermes/hermes-agent/plugins/memory/coppermind/`
2. Set in `~/.hermes/config.yaml`:

```yaml
memory:
  provider: coppermind
```

3. Disable the hook-based Coppermind plugin (to avoid duplication):

```yaml
plugins:
  disabled:
    - coppermind
```

4. Restart the gateway: `hermes gateway restart`

5. Verify: `hermes memory status` should show `Provider: coppermind` and `Status: available ✓`

## How It Works

- **prefetch()**: Sends a GET request to `/v1/memory/search` with the (truncated) user query. Results are formatted and injected as context.
- **sync_turn()**: After each turn, sends a POST to `/v1/ingest` with the conversation turn.
- **on_session_end()**: Creates and stores a session summary when the session ends.

## Query Truncation

To avoid HTTP 431 (Request Header Fields Too Large), queries are truncated to `COPPERMIND_MAX_QUERY_LENGTH` (default: 2000 characters). This is safe because semantic search works well with a reasonable query size. Adjust the limit if needed, but be aware of server header buffer limits.

## Troubleshooting

- **Memory not loading**: Check that `COPPERMIND_BASE_URL` is set and the server is reachable.
- **431 errors**: Reduce `COPPERMIND_MAX_QUERY_LENGTH`.
- **Provider shows as unavailable**: `hermes memory status` will indicate missing configuration.

## Note for Other Frameworks

This provider is Hermes-specific and lives inside the Hermes source tree. Other frameworks should continue using the hook-based Coppermind plugin from `~/.hermes/plugins/coppermind/`.