Hermes Integration

Hermes Agent is NousResearch's open-source agent CLI. CortexDB plugs into Hermes as a MemoryProvider, giving your Hermes agents persistent, hybrid-retrieval memory across sessions.

Installation

pip install cortexdb-hermes

Setup

export CORTEXDB_API_URL=https://api.cortexdb.ai
export CORTEXDB_API_KEY=cx_your_key

Then activate the provider inside Hermes:

/memory use cortexdb

That's it. The next user turn will pull long-term memory from CortexDB and the assistant's response will be persisted back automatically.

The Memory Cycle

The CortexDB provider implements the three-point memory cycle Hermes expects from memory plugins:

1. Pre-response injection — before each model call, system_prompt_block() injects relevant recalled context into the system prompt.
2. Post-response extraction — after each turn, sync_turn() persists the user/assistant pair to CortexDB on a background daemon thread so the agent loop never blocks on I/O.
3. Between-turn prefetching — queue_prefetch() fetches the next likely query in the background and caches the result for the following turn.

Tool Calls

The provider exposes three tools the model can invoke directly:

| Tool | Purpose | |---|---| | cortexdb_search | Search long-term memory for context relevant to the current question. | | cortexdb_remember | Persist a fact, preference, or decision. | | cortexdb_forget | Delete memories matching a query (requires an audit reason). |

Under the Hood

The provider wraps CortexDB's REST API. Equivalent calls:

# remember — store a turn
curl -X POST https://api.cortexdb.ai/v1/remember \
  -H "Authorization: Bearer $CORTEXDB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content": "User prefers Python over JS.", "tenant_id": "my-app"}'

# recall — retrieve context
curl -X POST https://api.cortexdb.ai/v1/recall \
  -H "Authorization: Bearer $CORTEXDB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "What language does the user prefer?", "tenant_id": "my-app"}'

Configuration

| Parameter | Default | Description | |---|---|---| | CORTEXDB_API_URL | https://api.cortexdb.ai | CortexDB server URL | | CORTEXDB_API_KEY | — | CortexDB API key (required) | | tenant_id | default | Multi-tenant isolation key | | agent_id | None | Optional agent identifier stored with memories |