integrations/hermes-agents/v0.1.0

# Release Notes for v0.1.0

This is the **initial release** of **hermes-memanto** — a [memory-agent provider](https://github.com/NousResearch/hermes-agent) that gives the **Hermes agent** typed long-term memory backed by [Memanto](https://memanto.ai) and the [Moorcheh.ai](https://moorcheh.ai) semantic database. With one `pip install`, one install command, and one config line, Hermes gains semantic recall across sessions, automatic turn capture, RAG-style answers, and per-profile memory isolation.

Unlike a passive "memory layer", every namespace in Memanto is a first-class **agent** (`memanto agent create/activate`), so this provider maps one Hermes identity to one Memanto agent.

## Improvements

### Memory Tools
The provider registers three tools with Hermes:
- **`memanto_remember`**: Persist a durable fact, preference, decision, goal, or instruction — with optional memory `type`, `tags`, and `confidence`.
- **`memanto_recall`**: Semantic search across the agent's memory — Hermes should always check here before asking the user to repeat stable information. Supports an optional `type` filter and `limit` (1–100).
- **`memanto_answer`**: Grounded RAG response synthesized **only** over the agent's stored memories — no extra LLM key required.
- **13 typed memory categories**: `fact`, `preference`, `goal`, `decision`, `artifact`, `learning`, `event`, `instruction`, `relationship`, `context`, `observation`, `commitment`, `error`.
- **Provenance metadata** on every write: `explicit_statement`, `inferred`, `corrected`, `validated`, `observed`, `imported`.

### Automatic Memory (no tool calls required)
- **Auto-recall** — before each turn, relevant memories are retrieved and injected into context as a `<memanto-memory>` block (prefetch). Tunable via `max_recall_results` and `min_confidence`.
- **Turn capture** — meaningful conversation turns are stored as `event` memories in the background (trivial acknowledgements and tiny messages are skipped).
- **Memory mirroring** — Hermes' built-in `memory` writes are echoed into Memanto, so manual saves and automatic recall share one store.
- **Profile isolation** — `agent_id: hermes-{identity}` scopes memory per Hermes profile; `{identity}` expands to the profile name at startup.

### Installation & Quickstart
- One-line install via `pip install hermes-memanto` (Python 3.10+), which pulls in the `memanto` SDK.
- A bundled `hermes-memanto-install` console script drops a **self-contained directory plugin** into `~/.hermes/plugins/memanto/` (copying the provider verbatim as the plugin's `__init__.py` plus its `plugin.yaml`), so the installed plugin needs only the `memanto` SDK at runtime — not this package.

  ```bash
  pip install hermes-memanto
  hermes-memanto-install
  export MOORCHEH_API_KEY=mch_xxxxxxxxxxxxxxxxxx   # https://console.moorcheh.ai/api-keys
  hermes config set memory.provider memanto
  ```

- Installer flags: `--hermes-home /path/to/.hermes` (defaults to `$HERMES_HOME` or `~/.hermes`) and `--force` to overwrite an existing install.
- First memory call **auto-creates** the agent and namespace; every subsequent call reuses the same persistent memory.
- Get your Moorcheh API key from the [console](https://console.moorcheh.ai/api-keys) (free tier: 100K ops/month).

### Provider Selection & Discovery
- Hermes discovers memory providers as **directories** under `$HERMES_HOME/plugins/<name>/` — each holding an `__init__.py` that exposes `register(ctx)` plus a `plugin.yaml`. This package ships exactly that.
- Memory providers are auto-detected as **exclusive** and selected via `memory.provider`, **not** `hermes plugins enable`:
  ```bash
  hermes config set memory.provider memanto
  ```
- `hermes memory setup` also lists **memanto** once installed, walks you through configuration, and writes `MOORCHEH_API_KEY` into `~/.hermes/.env` for you.

### Session & Lifecycle Management
- Sessions activate **lazily** on first use and are **warmed up in a background thread** at startup, so the first turn's recall doesn't pay agent-create + activate latency.
- A failed activation triggers a short **cooldown-and-retry** rather than a permanent kill switch — a transient backend blip or startup timeout doesn't disable the provider for the rest of the run, but a down backend isn't re-hit on every turn either.
- Configurable session lifetime via `session_duration_hours`.
- Writes are automatically **disabled in non-interactive contexts** (`cron`, `flush`, `subagent`) so background runs don't pollute memory; recall still works.
- Background captures and mirrored writes **bind the active client at schedule time**, so a delayed write always lands in the session that scheduled it.

### Configuration
After install, settings live in `$HERMES_HOME/memanto.json`:

| Key | Default | Description |
|---|---|---|
| `agent_id` | `hermes-{identity}` | Memanto agent id (memory namespace). `{identity}` expands to the Hermes profile name. |
| `pattern` | `tool` | Agent pattern used when auto-creating: `support`, `project`, or `tool`. |
| `auto_recall` | `true` | Inject relevant memories before each turn. |
| `auto_capture` | `true` | Store cleaned conversation turns as `event` memories. |
| `auto_create` | `true` | Create the agent on first use if it does not exist. |
| `mirror_memory_writes` | `true` | Echo Hermes' built-in `memory` writes into Memanto. |
| `max_recall_results` | `10` | Max memories formatted into prefetch context (1–100). |
| `min_confidence` | `null` | Drop recalled memories below this confidence (0.0–1.0). |
| `session_duration_hours` | `null` | Override Memanto session lifetime. |

| Environment variable | Required | Description |
|---|---|---|
| `MOORCHEH_API_KEY` | **yes** | Moorcheh API key (powers Memanto). |
| `MEMANTO_AGENT_ID` | no | Override the agent id (takes priority over the config file). |

### Security & Safety
- The API key lives **only** in the environment / `~/.hermes/.env` (`MOORCHEH_API_KEY`) — it is never persisted to `memanto.json`, even if passed through the setup wizard.
- Recalled memory is **sanitized before injection**: the `<memanto-memory>` wrapper delimiters are stripped from stored content, so a memory that happens to contain those tags can't break out of the context block and steer later turns.
- The `memanto` SDK is imported lazily, so the module loads even when the package isn't installed; the provider simply reports unavailable and stays inert until a key and the SDK are present.

### Shared Memory Across Integrations
hermes-memanto talks to the same Moorcheh-backed Memanto agents as the sibling integrations, so memory written by one is recallable from the others when they share an `agent_id`:

| Integration | Package | What it does |
|---|---|---|
| `integrations/mcp` | `memanto-mcp` | MCP server for any MCP-compatible client (Claude, Cursor, Windsurf, …). |
| `integrations/crewai` | `crewai-memanto` | CrewAI tools for multi-agent memory sharing. |
| `integrations/hermes-agents` | `hermes-memanto` | **This** — a memory provider for the Hermes agent. |

### Development

```bash
pip install -e ".[dev]"
pytest          # provider unit tests (no network; SdkClient is faked)
ruff check .
```

### Getting Started

```bash
pip install hermes-memanto
hermes-memanto-install
export MOORCHEH_API_KEY=mch_xxxxxxxxxxxxxxxxxx
hermes config set memory.provider memanto
```

Then start Hermes and tell it *"remember that I prefer concise answers"* — in a brand-new session tomorrow, ask *"what do I prefer?"* and Hermes will recall it before you finish typing.

### Documentation
- Integration README: [`integrations/hermes-agents/README.md`](integrations/hermes-agents/README.md)
- Memanto documentation: https://docs.memanto.ai
- Moorcheh base documentation: https://docs.moorcheh.ai
- Hermes agent: https://github.com/NousResearch/hermes-agent

This **v0.1.0** release brings Memanto's typed semantic memory to the Hermes agent — one install command, one config line, persistent context across sessions, and no infrastructure to operate.