# <a href="../README.md"><img src="https://raw.githubusercontent.com/skynetcmd/m3-memory/main/docs/m3_logo_icon.png" height="60" style="vertical-align: baseline; margin-bottom: -15px;"></a> ⚡ m3 Memory Integration for Hermes Agent

Welcome! This guide walks you through integrating **m3 Memory** (State-of-the-Art, vector-accelerated rich memory) with **Hermes Agent**.

By combining Hermes' powerful autonomous execution with m3's advanced 100+ tool multi-corpus memory system, you unlock SOTA long-term recall, semantic association, and tamper-proof cryptographic audit trails.

---

## 🌟 The Best of Both Worlds: Two Integration Modes

m3 is designed to be highly flexible. When hooking it up to Hermes Agent, you can choose between two main operating strategies:

### Option A: Optimal Replacement (Recommended for Unified SOTA Memory)
In this mode, you configure Hermes Agent to use **m3 as its primary memory provider**. 
* **Why do this?** Hermes' default file-based memory can grow slow and lacks semantic understanding. By replacing it with m3, Hermes gains instant access to **BGE-M3 vector embeddings**, **FTS5 hybrid search**, and automated **fact decay/curation**.
* **How it works:** Hermes loads the m3 memory provider plugin, redirecting all default read/write operations to the m3 SQLite memory catalog (`~/.m3/engine/agent_memory.db`).

### Option B: Parallel Co-existence (SOTA Rich Memory Toolbelt)
In this mode, you keep Hermes' default memory provider active, but load m3's **100+ MCP tools** directly into Hermes' runtime toolbelt.
* **Why do this?** This allows Hermes to continue using its lightweight built-in memory for simple context holding while granting it access to m3's specialized tools (like `memory_link`, `task_create`, `files_ingest`, and `chatlog_search`) for complex research and file-indexing tasks.

---

## 🚀 Step-by-Step Setup Guide

### Step 1: Run the m3 Setup Wizard
The easiest way to integrate m3 is through our automated interactive wizard:
```bash
python -m m3_memory.setup_wizard
```
1. The wizard will automatically probe common system locations (such as `%LOCALAPPDATA%\hermes`, `~/.hermes`, `~/hermes-agent`) to **autodetect** your Hermes Agent installation.
2. When prompted:
   > `Install the m3 SOTA memory-provider plugin into Hermes Agent? [y/N]`
   Type **`y`** to automatically copy the m3 provider files into the Hermes plugins tree.

### Step 2: Configure Environment Variables
Hermes Agent loads plugins dynamically and needs to find m3's core package in its search path. You must add the path to the m3 repository's `bin/` directory to the `PYTHONPATH` environment variable in Hermes' launch environment.

#### On Windows (PowerShell):
```powershell
$env:PYTHONPATH = "C:\path\to\m3-memory\bin;" + $env:PYTHONPATH
```

#### On Linux / macOS (Bash/Zsh):
```bash
export PYTHONPATH="/path/to/m3-memory/bin:$PYTHONPATH"
```

> [!TIP]
> To make this change permanent, add the environment variable to your terminal profile (`.bashrc` / `.zshrc`) or user-level environment settings in Windows.

### Step 3: Select the m3 Plugin in Hermes
Now, tell Hermes Agent to activate the m3 provider. Memory providers in Hermes are **single-select**.

1. Open your Hermes terminal configuration or run the plugin selector:
   ```bash
   hermes plugins
   ```
2. Navigate to the **Memory Providers** section and select **`m3`**.
3. Save and close.

---

## 🔍 Verifying the Connection

To verify that the bridge is functional, you can run the provider logic verification script:
```bash
python m3_memory/integrations/hermes/test_provider_logic.py
```
If successful, the test suite will print a green confirmation indicating that Hermes is successfully reading, writing, and querying the m3 memory database.

---

## 🛠️ Diagnostics & Curation
Once hooked up, you can monitor the health and performance of the memory bridge using the live interactive diagnostics dashboard built into m3:
```bash
python bin/chatlog_status.py --live
```
From the TUI monitor, you can:
* Press **`[S]`** to run the embedding sweeper.
* Press **`[D]`** or **`[A]`** to review or apply deterministic decay sweeps.
* Press **`[F]`** to ingest or sync external project directories directly into m3.

For more details on m3's capabilities, check out our primary documentation:
* [Main Documentation Gateway](../README.md)
* [MCP Tools Catalog](MCP_TOOLS.md)
* [Curation Guide](../agents/curate-memory.md)