ChainMemory Docs

HERMES AGENT

Hermes Agent is an open-source, provider-agnostic AI agent framework. ChainMemory integrates with Hermes via two paths: the MCP server (native tools inside chat) or the cm.py CLI wrapper (full control from terminal).

Prerequisites

Hermes Agent installed (Windows, macOS, Linux, WSL)
ChainMemory account with API key (format: aic_...)
Python 3.10+ (for cm.py wrapper)

Get Your API Key

ChainMemory accounts are created exclusively through the Chrome Extension:

Install ChainMemory Extension
Click the icon in your browser toolbar
Choose "Generate API Key automatically" (free wallet + 1 AIC) or "I already have a key"
Go to Settings → Connection and click "View" to copy your API key

Important: The Faucet (faucet.chainmemory.ai) distributes AIC tokens for on-chain operations, but does not issue API keys. The API key comes only from the Extension.

Option A: MCP Server (Chat Workflow)

The MCP server exposes ChainMemory as native tools inside Hermes chat. After configuration, you can say things like "Remember: we decided to use PostgreSQL" and Hermes will call the tool automatically.

Configuration

Edit ~/.hermes/config.yaml and add:

YAML — ~/.hermes/config.yaml
mcp_servers:
  chainmemory:
    command: "python"
    args: ["C:\\Users\\<user>\\.hermes\\skills\\chainmemory-mcp\\chainmemory_mcp_server.py"]
    env:
      CHAINMEMORY_API_KEY: "aic_..."
      CHAINMEMORY_BASE_URL: "https://api.chainmemory.ai/v1"
      CHAINMEMORY_DEFAULT_PROJECT: "default"

Restart Hermes after editing. The tools appear as mcp_chainmemory_* in chat.

Available MCP Tools

Tool	What it does
`mcp_chainmemory_save_memory`	Save a memory
`mcp_chainmemory_list_memories`	List / search memories
`mcp_chainmemory_get_profile`	Account info
`mcp_chainmemory_list_projects`	List projects
`mcp_chainmemory_get_balance`	AIC balance + faucet URL
`mcp_chainmemory_get_blockchain_stats`	Chain stats
`mcp_chainmemory_update_memory_tags`	Retag a memory
`mcp_chainmemory_archive_memory`	Archive / unarchive

Option B: cm.py Wrapper (CLI / Scripts)

cm.py is a Python CLI that wraps the REST API. It handles auth headers, pacing, and retries. Install it via the ChainMemory skill:

bash
hermes skills install chainmemory

Then configure your key:

bash
chmod 600 ~/.hermes/chainmemory.env

Commands

Command	What it does
`cm whoami`	Show account, tier, quota
`cm projects`	List all projects
`cm save "text" --project my-app`	Save a memory
`cm recall --project my-app`	Recall recent memories
`cm search "query" --project my-app`	Semantic search
`cm state my-app`	Project State
`cm seal my-app`	Anchor state on-chain (irreversible)
`cm verify my-app`	Public verification (no auth)

Option C: REST API Direct

Any HTTP client works. Base URL: https://api.chainmemory.ai/v1. Auth header: x-api-key: aic_... (not Authorization: Bearer).

Important Notes

Auth header: Use x-api-key, not Authorization: Bearer.
Rate limits: 30–600 req/min depending on plan.
The state does not build itself: there is no backend consolidation and no automatic trigger. The Project State changes only when a client proposes operations through update_project_state (MCP) or POST /v1/project/:name/state/ops (API). Waiting will not produce a state — asking for one will.
What "seal" means here: in ChainMemory own API and MCP server, seal makes a single memory permanently immutable (POST /v1/seal/:id, which takes your memory number). The Project State is anchored as part of consolidation, not by sealing. cm.py is a third-party wrapper and may map its commands differently.
Windows paths: In config.yaml, use double backslashes: C:\\Users\\<user>\\...

Verify Setup

bash
# Via MCP (in chat)
"Save this: We decided to use PostgreSQL for the primary database"

# Via CLI
cm whoami
cm save "We decided to use PostgreSQL for primary DB" --project my-app --tags decision,stack
cm state my-app
cm verify my-app