hermes-gbrain-honcho

Run Honcho + GBrain together in Hermes

A practical guide for giving a Hermes agent two kinds of memory:

Honcho = remembers the person, the relationship, and the conversation history
GBrain = remembers the notes, sources, links, and evidence
Hermes = talks to the user, calls tools, and decides which layer to use

A bio-infographic view of the stack: Hermes routes the work, Honcho carries relationship memory, and GBrain carries source-backed evidence.

Why do this?

A good agent needs to know two very different things.

It needs to know you: how you work, what you prefer, what happened in earlier sessions, what not to repeat, what tone and level of detail fit.

It also needs to know the material: notes, docs, research, meeting records, source pages, links, contradictions, and what the evidence actually says.

Those are not the same job.

If you put everything into conversation memory, your agent gets warm but mushy. It may remember that something matters, but it cannot reliably show where the claim came from.

If you put everything into a document brain, your agent gets source material but loses the relationship. It can search your notes, but it does not really know how to work with you.

So this guide uses both:

Honcho remembers the relationship. GBrain remembers the corpus. Hermes routes between them.

What this repo gives you

This is not a new memory product and not a fork of any upstream project. It is a wiring guide.

It shows how to run:

• Hermes Agent as the agent runtime;
• Honcho as the session/user/relationship memory layer;
• GBrain as the explicit source-backed brain;
• GBrain as a local HTTP MCP service that Hermes can call safely;
• a conservative bootstrap script that checks before it changes things.

The goal is simple: an agent that can say, “I know how you like to work, and I can also show you the source.”

Who this is for

You can read this guide at two depths.

If you are a Hermes user who mostly wants the idea, read the first half: why the split exists, what each piece does, and when the agent should use each layer.

If you are wiring the stack yourself, keep going into the plumbing, install steps, config templates, security notes, and operations pages.

If you are handing this repo to an AI agent, point it at AGENTS.md first. For a shorter execution path, use INSTALL_FOR_AGENTS.md.

You do not need to understand every Honcho or GBrain internals detail to use the pattern. The short version is enough to start:

Honcho keeps the agent personally aware.
GBrain keeps the agent source-grounded.
Hermes decides which one to call.

The pieces

Start here if you only want the mental model. The plumbing comes after this section.

Hermes

Hermes is where the agent lives.

It handles the outer loop: chat, API clients, messaging gateways, tools, skills, cron jobs, webhooks, providers, and MCP servers. In this stack Hermes is not trying to be the whole memory system. It is the part that asks: what kind of context does this task need?

Use Hermes for:

• receiving messages from CLI, Matrix, Telegram, API clients, cron jobs, and webhooks;
• calling tools and MCP servers;
• routing model/provider calls;
• loading skills and procedures;
• deciding whether a task needs Honcho, GBrain, both, or neither;
• taking the final action.

Hermes is the hands and voice of the stack. Honcho and GBrain make those hands less forgetful.

Honcho

Honcho is more than long-term memory. Its upstream story is sharper than that:

Honcho is a memory system that reasons.

Instead of only retrieving old messages that look similar to the current query, Honcho stores interactions and reasons over them in the background. It builds evolving peer representations: conclusions, summaries, and peer cards about users, agents, groups, projects, or other entities that change over time.

The basic Honcho loop is:

1. Store messages, events, documents, or tool traces on sessions.
2. Reason in the background over what happened.
3. Update representations for the peers involved.
4. Query those representations through context/search/chat endpoints.
5. Inject the result into the next model call.

That reasoning layer matters because a lot of useful memory is not a literal quote. It is the pattern behind the quotes: preferences, recurring corrections, contradictions, habits, relationship state, and what one peer has actually observed about another.

A few upstream terms are useful to know:

• Representations — the evolving model of a peer, built from conclusions, summaries, and peer-card facts.
• Reasoning — inference over messages rather than plain vector recall.
• Perspective — optional peer-to-peer memory, so one participant can model only what it has actually observed.
• Chat / dialectic-style querying — natural-language questions over Honcho’s reasoning, with reasoning_level choices from minimal to max when you want to trade speed for depth.
• Dreaming — an experimental consolidation cycle. Waking reasoning captures what happened; dreaming reflects on what the accumulated conclusions mean.

Use Honcho for:

• who the user is;
• how the user likes to work;
• what happened in recent sessions;
• stable preferences and corrections;
• relationship state and conversational continuity;
• the assistant’s own peer representation: what it tends to do well, where it gets corrected, and how it should show up;
• mutual perspective: what the assistant has observed about the user, what the user appears to expect from the assistant, and how the relationship has changed over time;
• group or workspace context when there are more peers than one user and one assistant;
• prompt-ready context that should shape the next answer.

That makes Honcho closer to a relational reasoning layer than a passive memory box. It can model more than “what happened in the session”: it can help the agent reason about the participants, the collaboration, the accumulated conclusions, and the assistant’s own operating pattern.

Honcho is the reason the agent does not start from zero every morning. It gives the agent continuity that feels earned, not bolted on.

GBrain

GBrain has a different job. Its upstream story is:

Search gives you raw pages. GBrain gives you the answer.

GBrain is the explicit brain/corpus layer: markdown pages, chunks, embeddings, source links, schema-aware page types, graph edges, and synthesis tools that let an agent work over a body of material without pretending it “just remembers.”

The important distinction is search versus brain:

• gbrain search finds relevant pages/chunks using hybrid retrieval.
• gbrain think uses retrieval, graph context, citations, and gap analysis to produce a sourced answer.

That is why GBrain is valuable for research and operational knowledge. It is more than a bucket of notes. It gives the agent a place to ask, “what does the corpus actually support, where are the sources, and what is missing?”

The useful parts, in normal language:

• Human-readable notes — markdown pages stay editable and git-friendly.
• Better retrieval — GBrain can combine semantic search, keyword search, graph links, source weighting, and reranking.
• A graph — links between pages become relationships the agent can follow.
• Cited synthesis — answers can point back to source pages instead of returning a pile of chunks.
• Gap analysis — good answers say what the brain does not know, where pages are stale, or where claims conflict.
• Schema packs — page and link types give the corpus structure, so a person, meeting, concept, project, or source page can behave differently.
• Local or bigger database engines — PGLite is the zero-config local default; Postgres/pgvector is the path for concurrency, teams, and larger brains.
• MCP — Hermes can call GBrain through standard tools instead of shelling out ad hoc.

Use GBrain for:

• source notes and documents;
• research trails;
• architecture docs;
• meeting notes;
• project specs;
• entity pages and timelines;
• evidence-backed synthesis;
• questions where citations, links, contradictions, or “what is missing?” matter.

GBrain is the reason the agent can say, “the corpus supports this” instead of vaguely claiming it remembers.

The plumbing

Recommended local layout:

Hermes gateway/API     http://127.0.0.1:8642
Honcho API             http://127.0.0.1:8000
GBrain HTTP MCP        http://127.0.0.1:3131/mcp

Flow:

User / API / gateway / cron
        │
        ▼
Hermes Agent
        │
        ├── Honcho
        │     relationship, preferences, peer/session context
        │
        └── GBrain
              notes, pages, graph links, citations, synthesis

The important operational choice is this:

Run one persistent GBrain HTTP service.
Let that service own the GBrain database.
Point Hermes at it over MCP.

That avoids the common local PGLite problem where multiple short-lived gbrain serve processes fight over the same brain database.

For dream/autopilot work, be even more conservative:

stop the HTTP service → run gbrain dream --dry-run → inspect → restart the service

Dreaming should start as reviewed proposals, not unattended mutation. In the tested small-box PGLite path, retrieval and controlled synthesis were stable first; dream dry-runs worked after routing dream models through an available provider, preserving --dry-run through sub-phases, and keeping one database owner. If dream cycles matter or multiple clients need concurrent access, move GBrain to Postgres/pgvector before scheduling autonomy.

Model routing should also match the risk of each phase. A practical default is:

GBrain work	Suggested model lane
Query expansion, structural extraction, link/frontmatter cleanup, candidate-only dream proposals	Cheap/current utility model, such as Gemini Flash
Cited think, branch ranking, contradiction judgment, accepting/promoting durable takes, medical or business conclusions	Frontier/deep model, such as GPT-5.5
Embeddings and reranking	Dedicated embedding/reranking models

The key rule is cheap scouts, expensive judges. Let the cheap lane generate candidates, but do not let it quietly change the durable corpus or belief state.

When Hermes should use what

User asks	Use	Why
“What did we decide yesterday?”	Honcho / sessions	Conversation continuity matters most.
“How do I usually like this formatted?”	Honcho	This is preference memory.
“What does this note/source say?”	GBrain	The answer should come from the corpus.
“Which docs support this claim?”	GBrain	Needs retrieval, links, and citations.
“Given what you know about me, what should I do with this research?”	Honcho + GBrain	Needs personal context and evidence.
“Run this one-off command.”	Neither, usually	Not every task needs durable memory.

Why not just use one memory layer?

Honcho alone

Honcho is excellent for continuity, but it should not become a dumping ground for every paper, spec, note, and source document.

If you use it as the whole knowledge base, you lose clean citation boundaries.

GBrain alone

GBrain is excellent for source-backed knowledge, but it is not meant to infer the whole relationship every turn.

If you use it as the only memory layer, the agent becomes a document searcher with weak personal continuity.

Together

Together they do the thing people actually want:

personal context + source-backed evidence + tool-using agent

That is the pattern.

Benefits and trade-offs

You get	You pay with
A warmer agent that remembers how to work with the user	You need rules for what belongs in memory
Source-backed answers instead of vague “I remember” claims	You need a real corpus: notes, links, imports, upkeep
Cleaner separation between personal memory and research evidence	More services to watch and back up
Local-first database ownership	Cloud models/embeddings may still see requests unless you choose local providers
Stable GBrain access through one HTTP MCP service	Service management and token handling
Simple PGLite pilot	Postgres is better once concurrency or team use matters

Start small. Keep it local. Expose read-only tools first. Add write/admin tools only after backups and rollback are boring.

Quick start, safely

Start with a dry run:

curl -fsSL https://raw.githubusercontent.com/elkimek/hermes-gbrain-honcho/main/install.sh -o /tmp/hermes-gbrain-honcho-install.sh
bash /tmp/hermes-gbrain-honcho-install.sh --dry-run

Then run local checks only:

bash /tmp/hermes-gbrain-honcho-install.sh --check-only

Then, if the output makes sense:

bash /tmp/hermes-gbrain-honcho-install.sh

The script is conservative by default:

• it does not overwrite an existing GBrain service unless you pass --force-overwrite;
• it does not start services unless you pass --start-services;
• it does not install Bun/GBrain unless you pass --install-missing;
• it writes placeholders, not secrets;
• it keeps the examples localhost-first.

What to read next

1. Installation — get the pieces running safely.
2. Configuration — wire Hermes to Honcho and GBrain.
3. Routing rules — teach the agent when to use each layer.
4. Operations — keep the services healthy.
5. Security — keep secrets, ports, and MCP tools under control.
6. Evaluation — prove the stack improves answers.
7. Production readiness — release gates before calling the stack production-ready.
8. Reflex automation — optional n8n heartbeat/webhook layer.
9. Eval harness — repeatable checks for guarded production readiness.
10. Upstream alignment — check the wording against the upstream projects.

Reference pages:

• Agent instructions
• Install for agents
• Component guide
• Architecture
• Troubleshooting
• Honcho self-hosting — upstream Docker/local setup before wiring it into Hermes.

Repository map

Path	Purpose
AGENTS.md	Instructions for AI agents using this repo
INSTALL_FOR_AGENTS.md	Short install runbook for AI agents
install.sh	Conservative bootstrap/check script
templates/	Copyable config templates
docs/installation.md	Manual install path and bootstrap flags
docs/configuration.md	Hermes, Honcho, and GBrain config examples
docs/routing.md	When to use Honcho, GBrain, both, or neither
docs/operations.md	Health checks, imports, embeddings, restarts, backups
docs/security.md	Secrets, localhost defaults, MCP boundaries
docs/evaluation.md	How to test whether the stack helps
docs/production-readiness.md	Release gates for guarded production use
docs/reflex-automation.md	Optional n8n heartbeat/webhook reflex layer
docs/eval-harness.md	Repeatable production eval cases and live smoke checks
docs/upstream-alignment.md	Cross-check against upstream projects

Upstream projects

• Hermes Agent
• Honcho, including its self-hosting guide
• GBrain

Production readiness

See docs/production-readiness.md for the release gates before calling the stack production-ready.