hermes - 💡(How to fix) Fix [Feature]: GhostCrab MCP + mindBrain SQLite : structured domain navigation for Hermes-Agent sessions

Problem or Use Case

What problem this solves

Hermes-Agent sessions are transient by design.

When an agent stops — a coding session ends, a workflow completes, a context window fills — everything it learned, every decision it made, every link it discovered disappears. The next session starts from scratch. The same context rebuilt. The same questions asked again.

This request adds two complementary components that solve this without touching Hermes-Agent or any MCP client's core behavior.

What a domain looks like in practice

A domain is any bounded context where an agent needs to reason over structured relationships : not just retrieve text.

mindBrain separates two levels:

Ontology (the model) : the schema of a domain: entity types, relationship types, constraints, vocabularies. Defined once, persisted in SQLite locally — no hosted service required.

Knowledge Graph (the projected instance) : the populated graph: real entities, real edges, real state : queryable across sessions.

Example: multi-agent project delivery

Ontology (model)              Knowledge Graph (instance)
─────────────────             ──────────────────────────
Project                       "Platform Modernization Q3"
└── has Task                  └── Task: "Rotate JWT keys"
      └── assigned_to               assigned_to: DevAgent
      └── status                    status: blocked
      └── depends_on          Task: "Define ERP contract"
      └── has Blocker         Blocker: "ERP API scope undefined"
Decision                      Decision: "Stateless JWT over Redis"
└── affects Component               affects: "Auth Service"

Any agent Hermes-Agent starting a new session calls ghostcrab_pack and receives the full structured context instantly: active tasks, their blockers, linked decisions, dependency chain. No re-reading prior transcripts. No reconstructing what happened last time.

Example: ERP domain

Ontology (model)              Knowledge Graph (instance)
─────────────────             ──────────────────────────
Account                       "Acme Corp" (tier=enterprise)
└── has CostCenter            └── CostCenter: "Engineering"
└── has ApprovalFlow          └── ApprovalFlow: PO > €5k → CFO
GLEntry                       GL-20260501: amount=€12,400
└── linked_to CostCenter            linked_to: "Engineering"

An agent resolving a billing anomaly navigates account structure, approval rules, and GL history across sessions. ghostcrab_search retrieves the relevant slice. ghostcrab_traverse follows linked approvers and cost center hierarchy. No CSV re-injection. No context reconstruction.

Example: CRM domain

Ontology (model)              Knowledge Graph (instance)
─────────────────             ──────────────────────────
Account                       "NovaTech" (tier=enterprise)
└── has Contact               └── Contact: "Maria Chen" (VP Engineering)
└── has Deal                  └── Deal: "Platform License" (stage=negotiation)
└── has Interaction           └── Call: 2026-05-14, sentiment=positive
└── has Constraint            └── Constraint: "No multi-year commitment"

An agent preparing a renewal call loads the account context with ghostcrab_pack, finds the deal stage, the last interaction sentiment, and the contractual constraint in a single structured response. No re-reading CRM export. No asking "what did we discuss last time?".

Example: Customer Support domain

Ontology (model)              Knowledge Graph (instance)
─────────────────             ──────────────────────────
Ticket                        TK-9821: priority=critical
└── linked_to Component       └── linked_to: "Auth Service"
└── references Incident       └── Incident: "JWT outage 2026-04-30"
KnownIssue                    KI-44: "Token expiry on clock skew"
└── affects Component               affects: "Auth Service"
└── has Resolution            Resolution: "Force clock sync + rolling restart"

An agent resolving TK-9821 calls ghostcrab_traverse from the ticket and immediately surfaces the linked incident, the known issue, and its resolution — without searching knowledge bases or escalating blindly.

The meta-ontology: where mindBrain becomes strategic

Each domain above is useful alone. The real leverage is connecting them.

         ERP ←──────────────────┐
                                 │
         CRM ←─────── mindBrain ─┼──→ Project Management
                                 │
         Support ←───────────────┘
                                 │
                                 └──→ Knowledge / Documentation

A Hermes-Agent session working on a cross-domain task — say, an enterprise renewal involving a billing dispute, an open critical support ticket, and a stalled deal — navigates all four domains from the same local registry in one pass.

The agent does not re-explain the landscape. It does not summarize prior sessions from memory. It calls ghostcrab_pack and gets structured, typed context directly.

This is the difference between memory and ontology. Memory stores what was said. Ontology stores what is true and how things relate.

Two components, one integration

mindBrain Personal (SQLite : local edition)

The data layer. Zero infrastructure. A single local file. It organizes domain knowledge into three constructs:

• Facts : typed, durable entities — decisions, blockers, tasks, concepts, constraints
• Links : named relations between entities — depends_on, affects, linked_to, KNOWS_ABOUT, ...
• Facets : indexed attributes that make entities filterable and searchable without full-text ambiguity

Agents don't search through unstructured text. They navigate a structured graph. ghostcrab_search finds by type and facet. ghostcrab_traverse follows links. Both return structured results, not ranked passages.

GhostCrab Personal MCP

The gateway layer. A local stdio MCP server that gives any MCP-capable agent direct access to MindBrain Personal.

Hermes-Agent 
└── GhostCrab Personal MCP  (stdio, local)
      └── mindBrain SQLite
            ├── facts     — typed, durable entities
            ├── links     — named relations (graph)
            └── facets    — indexed query dimensions

No hosted service. No network dependency. No vendor lock-in.

Why this belongs outside Hermes-Agent core

It should stay external.

Any MCP-capable client can point to GhostCrab Personal over stdio. The integration requires zero changes to Hermes-Agent.

Domain structure is specific to each workspace and project. A general-purpose memory layer cannot know in advance what is worth keeping and how to relate it. That decision belongs to the agent and its user.

If GhostCrab is absent : the agent behaves exactly as before. If mindBrain is empty : the agent starts with a blank workspace and builds its memory through normal ghostcrab_remember and ghostcrab_upsert calls.

Setup

One install. One command. Any MCP client.

npm install -g @mindflight/ghostcrab-personal-mcp
gcp brain up

Then point the MCP client to the local server.

Hermes-Agent (mcp.json or equivalent)

{
  "mcpServers": {
    "ghostcrab": {
      "command": "gcp",
      "args": ["mcp", "stdio"],
      "transport": "stdio"
    }
  }
}

No port. No external service. GhostCrab runs as a subprocess.

Agent lifecycle: before, during, after

Minimal first-contact path: ghostcrab_status → ghostcrab_pack → ghostcrab_remember → ghostcrab_search

remember vs upsert:

• ghostcrab_remember — for durable facts and decisions that do not change (append)
• ghostcrab_upsert — for mutable state: task status, blocker state, current phase (update in place)

Three local demo scenarios

Demo 1: Resume a coding session

# Session 1 — agent stores a decision
ghostcrab_remember("JWT rotation requires ERP scope defined first — blocked on API contract")

# Session 2 — new session, agent recovers context instantly
ghostcrab_pack() → returns all active project context including the blocker note

Demo 2: Track a blocker across sessions

ghostcrab_upsert({ type: "Blocker", slug: "jwt-rotation-blocked", status: "active" })
ghostcrab_learn("jwt-rotation-blocked", "depends_on", "erp-api-contract")

# Any later session
ghostcrab_traverse("jwt-rotation-blocked") → returns the full dependency chain

Demo 3: Search prior decisions before making a change

ghostcrab_search({ type: "Decision", facets: { component: "Auth Service" } })
→ returns all decisions affecting Auth Service, including rationale and status

→ Full configuration, skill files, and demo walkthrough: https://github.com/mindflight-orchestrator/ghostcrab-personal-mcp/blob/main/ghostcrab-integrations/hermes-agent/SKILL_ghostcrab-mcp.md

https://github.com/mindflight-orchestrator/ghostcrab-personal-mcp/blob/main/ghostcrab-integrations/hermes-agent/SKILL_hermes-agent-ghostcrab-architect-skill.md

Scope of this request

• Adds GhostCrab Personal MCP + mindBrain Personal SQLite to the Hermes-Agent integrations catalog
• No changes to Hermes-Agent or any MCP client
• No hosted dependency — fully local, zero infrastructure
• Works equally for Claude Code, Codex, and any stdio MCP client

Proposed Solution

Setup

One install. One command. Any MCP client.

npm install -g @mindflight/ghostcrab-personal-mcp
gcp brain up

Then point the MCP client to the local server.

Hermes-Agent / Claude Code (mcp.json or equivalent)

{
  "mcpServers": {
    "ghostcrab": {
      "command": "gcp",
      "args": ["mcp", "stdio"],
      "transport": "stdio"
    }
  }
}

No port. No external service. GhostCrab runs as a subprocess.

Alternatives Considered

This service is unique as it merge in a deterministic way 2 worlds : dimensions (facets) and graphs (semantic edges). You could manage multiples ontologies on the same kind of content, you could build meta-ontologies to merge different domains (knowledge, data silos, ....). And it generates pre-built combinations of main requests (we call them "projections") that give agent information in seconds. You can have a dashboard view rendered in milliseconds in JSON and the rendered in 700 ms by Hermes-Agent to a user.

Feature Type

New tool

Scope

Small (single file, < 50 lines)

Contribution

• I'd like to implement this myself and submit a PR

Debug Report (optional)