hermes-mcp Gateway Smoke Tests

Companion note for unified-agent-memory-fabric.

A gateway being up is not enough. Every wrapped tool has to work through the actual MCP client path.

Tools to verify

vault_read
vault_search
mem0_list
mem0_search
gbrain_search
gbrain_list_pages

Failure mode 1: stale mem0 route

Symptom:

mem0_list works
mem0_search fails or returns method errors

Cause:

old: /memories/search
new: /search

Failure mode 2: OAuth success with empty gbrain scope

Symptom:

gbrain token mints successfully
gbrain search returns []
local gbrain CLI returns real results

Cause: the OAuth client can be scoped away from the local source.

Practical same-host fix:

1. Add gbrain OAuth env to the gateway service.
2. Try OAuth first.
3. For a trusted same-host gateway, fall back to the local gbrain CLI when OAuth returns an empty local-source view.

Source assessment excerpt

Specs — Unified Agent Memory

Spec 1: Phase 0 — Assessment Health Checks

1.1 Mem0 Health Check

Action: Verify mem0-new deployment is running, reachable, and serving queries. Commands:

# Check containers
ssh server 'docker ps --filter name=mem0'
 
# Check API health
curl -s https://memory.example.com/healthz
 
# Check dashboard
curl -s -o /dev/null -w "%{http_code}" https://memory.example.com
 
# Check auth config
ssh server 'cat /srv/mem0-new/.env | grep -i auth'
 
# Test a memory write+read
curl -s -X POST https://memory.example.com/memories \
  -H "Authorization: Bearer REDACTED" \
  -H "Content-Type: application/json" \
  -d '{"user_id": "goku", "messages": [{"role": "user", "content": "test ping from phase 0"}]}'

Pass criteria: API returns 200, memory is stored and searchable.

1.2 Supabase PG Inventory

Action: Check database capacity, pgvector extension, connection limits. Commands:

# Connect and check
ssh server 'psql -h supabase-db -p 5433 -U postgres -d postgres -c "
  SELECT pg_size_pretty(pg_database_size(current_database())) as db_size;
  SELECT count(*) FROM pg_available_extensions WHERE name = '\''vector'\'';
  SHOW max_connections;
"'

Pass criteria: pgvector available, sufficient DB size for mem0 + gbrain, connection limit > 20.

1.3 CouchDB Compatibility

Action: Check if Docker can run CouchDB, port 5984 availability, SSL setup via existing Caddy. Commands:

# Check port
ssh server 'ss -tlnp | grep 5984 || echo "port 5984 free"'
 
# Check Caddy config
ssh server 'cat /etc/caddy/Caddyfile 2>/dev/null || docker exec caddy cat /etc/caddy/Caddyfile 2>/dev/null'
 
# Check Docker network
ssh server 'docker network ls'

Pass criteria: Port free, Caddy reverse proxy can be configured, Docker operational.

1.4 gbrain Prerequisites

Action: Check bun, Node.js, disk space. Commands:

ssh server 'bun --version 2>/dev/null || echo "bun not installed"'
ssh server 'node --version'
ssh server 'df -h /'

Pass criteria: bun >= 1.0, node >= 20, disk > 10GB free.

1.5 Agent Profile Inventory

Action: Document what tools each agent profile has and what’s missing. Checklist:

• server/poke: has mem0 tools? has vault read/write? has gbrain?
• mac/poke: has mem0 tools? has vault read/write? can reach server MCP?
• Clawd (server gateway): configured for delegation? has mem0?
• Machine (discord): can it reach mem0? can it read vault?
• hermes-mcp: currently proxies to dashboard_ws. can it proxy to gbrain + mem0 too?

---

Spec 2: Phase 1 — LiveSync Deployment

2.1 CouchDB on server

Docker Compose:

services:
  couchdb:
    image: couchdb:3
    container_name: couchdb
    ports:
      - "127.0.0.1:5984:5984"
    environment:
      - COUCHDB_USER=admin
      - COUCHDB_PASSWORD=<secret>
    volumes:
      - couchdb_data:/opt/couchdb/data
    restart: unless-stopped
 
volumes:
  couchdb_data:

Steps:

1. Generate COUCHDB_PASSWORD= store in .env
2. Deploy compose
3. Create system database _users, _replicator, _global_changes
4. Create vault database vault-write
5. Configure CORS for Obsidian clients
6. Set up Caddy reverse proxy for couchdb.livesync.goku.codes
7. Enable SSL

2.2 Obsidian LiveSync Plugin

Steps:

1. Install plugin on mac Obsidian via BRAT or Community Plugins
2. Install plugin on any Obsidian client that accesses vault-write
3. Configure remote: couchdb.livesync.goku.codes
4. Configure sync: send all markdown files, ignore .git/ .obsidian/ .smart-env/
5. Do initial one-time sync from git state

2.3 Migration & Verification

Steps:

1. Keep git as fallback
2. Test: edit a note on mac — verify it appears on server within 10s
3. Test: edit a note on server — verify it appears on mac within 10s
4. Test: concurrent edits (same file, different sections)
5. Configure git backup interval (daily auto-commit from server)

---

Spec 3: Phase 2 — gbrain Installation

3.1 Install gbrain

Commands:

ssh server 'export NVM_DIR="$HOME/.nvm" && . "$NVM_DIR/nvm.sh" && nvm use 22 && bun install -g github:garrytan/gbrain'

3.2 Database Setup

Commands:

# Create gbrain database in supabase PG
ssh server 'psql -h supabase-db -p 5433 -U postgres -d postgres -c "CREATE DATABASE gbrain;"'

3.3 Initialize & Sync

Commands:

ssh server 'cd /srv && gbrain init --vault /srv/vault-write --engine postgres --db-url postgresql://user:REDACTED@db:5432/database'
ssh server 'gbrain sync'

3.4 MCP Server

Commands:

ssh server 'gbrain mcp start --port 8765 --auth token:<GBRAIN_TOKEN>'

3.5 Hermes Skill

Create a Hermes skill that wraps gbrain MCP tools: query, search, write, summarize.

For deeper notes on the memory layers these tools access, see unified-agent-memory-gbrain-mem0.