GhostCrab MCP + mindBrain SQLite : structured domain navigation for ADK agents sessions

[FrancoisLamotte]

What problem this solves

Google ADK gives developers precise control over sessions, tools, memory, callbacks,
and runners. The architecture is well-designed — and it leaves one slot explicitly
unfilled: BaseMemoryService.

The three native options are InMemoryMemoryService (keyword match, non-persistent),
VertexAiMemoryBankService (LLM-extracted, cloud-only), and VertexAiRagMemoryService
(vector similarity). None provides a typed, faceted, self-hosted ontology registry.
Facts extracted by one agent are invisible to the next. Context rebuilt from scratch
at every session. Knowledge scattered and unstructured.

This request adds two complementary components that fill that slot without touching ADK core.

---

What a domain looks like in practice

A domain is any bounded context where agents need 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, shared across every agent and every session.

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

Example: multi-agent project delivery

Ontology (model)              Knowledge Graph (instance)
─────────────────             ──────────────────────────
Project                       "Platform Modernization Q3"
└── has Epic                  └── Epic: "Auth Refactor"
      └── has Task                  └── Task: "Rotate JWT keys"
            └── assigned_to               assigned_to: DevAgent
            └── status                    status: blocked
            └── depends_on          Task: "Define ERP contract"
Component                     Component: "Auth Service"
└── constrained_by            ADR: "Stateless JWT over Redis"
Agent                         OrchestratorAgent
└── owns Task                       → owns "Rotate JWT keys"
└── produces Finding          Finding: "JWT rotation requires ERP scope"

OrchestratorAgent calls search_memory("what is blocking DevAgent this sprint?") →
MindBrain returns the full dependency chain in a single structured query.
No inference cost. No context-window dump. No re-reading session transcripts.

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"

A FinanceAgent resolving a billing anomaly navigates
account structure, approval rules, and GL entry history
without re-injecting spreadsheet data into each session.
The ADK PreloadMemoryTool injects the relevant slice automatically before each LLM call.

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"

A SalesAgent preparing a renewal call retrieves
account tier, active deal stage, recent interaction sentiment,
and contractual constraints in one faceted query.
No re-reading CRM export. No LLM re-extraction of the same data.

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"
└── assigned_to Agent         └── SupportAgent-3
KnownIssue                    KI-44: "Token expiry on clock skew"
└── affects Component               affects: "Auth Service"
└── has Resolution            Resolution: "Force clock sync + rolling restart"

A SupportAgent resolving TK-9821 immediately retrieves
the linked incident, the known issue, and its resolution history
via get_relations("Auth Service", "KnownIssue") —
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 single ADK multi-agent team working on a cross-domain task —
say, an enterprise renewal involving a billing dispute,
an open critical support ticket, and a stalled deal —
can query all four domains from the same structured registry in one pass.

The ADK OrchestratorAgent does not relay natural-language context
between specialized sub-agents. It reads the graph directly.
Relations carry their semantics natively. Context does not degrade across hops.

That is the difference between memory and ontology.
ADK's search_memory() interface was built for exactly this kind of backend.
MindBrain provides the implementation that Vertex AI cannot run on-premises.

---

Two components, one integration

mindBrain (SQLITE : Personal edition)

The data layer. It organizes domain knowledge into three constructs:

• Facets : typed dimensions that structure a domain (status, priority, tier, domain, agent_id, sprint, sentiment, ...)
• Semantic graphs : edges that capture typed relationships between entities (ASSIGNED_TO, DEPENDS_ON, REFERENCES, CONSTRAINS, AFFECTS, LINKED_TO, ...)
• Projections : pre-computed views of complex queries, surfaced at zero inference cost — phase readiness, agent workload, blocker chains, critical path

Agents don't search through data. They navigate a structured domain.
Embedding search is available for unstructured recall, but it's the fallback,
not the default.

GhostCrab MCP

The gateway layer. An MCP server that gives ADK agents the tools to:

• Read and write the shared ontology registry without direct database access
• Execute faceted search, graph traversal, and projection queries
• Receive structured memory injections via PreloadMemoryTool before each LLM call
• Persist session events and decisions into durable ontology nodes via after_agent_callback

GhostCrab is a protocol bridge. mindBrain exists and operates independently.

ADK LlmAgent / multi-agent pipeline
└── GhostCrab MCP  (stdio local, or streamable-http deployed)
      └── mindBrain SQLITE
            ├── facets       — typed domain dimensions
            ├── graphs       — semantic edges across domains
            └── projections  — shared context for any agent at any session

---

Why this belongs outside ADK core

It should stay external.

ADK already provides the right extension slot: BaseMemoryService.
MindBrain implements that interface — placing GhostCrab exactly where ADK
expects a persistent, queryable context registry, with no modification to ADK itself.

MindBrainMemoryService replaces the Vertex lock-in with a self-hosted,
air-gap compatible backend. Teams that cannot use VertexAiMemoryBankService
for compliance or cost reasons have a structured alternative.

If GhostCrab is absent : ADK behaves exactly as before.
If mindBrain is empty : agents start with a blank namespace and populate it
through normal session events and after_agent_callback ingestion.

---

Setup

Two integration paths, independently usable and combinable:

Path 1 — MCPToolset via stdio (local, zero infrastructure)

from google.adk.agents import LlmAgent
from google.adk.tools.mcp_tool.mcp_toolset import MCPToolset, StdioConnectionParams
from mcp.client.stdio import StdioServerParameters

ghostcrab_toolset = MCPToolset(
    connection_params=StdioConnectionParams(
        server_params=StdioServerParameters(
            command="ghostcrab",
            args=["--transport", "stdio", "--db", "./mindbrain.db"],
        ),
        timeout=30
    )
)

agent = LlmAgent(
    model="gemini-2.5-flash",
    name="orchestrator_agent",
    tools=[ghostcrab_toolset],
    instruction="Use GhostCrab tools as the single source of truth for all project context.",
)

GhostCrab launches as a subprocess. mindbrain.db is created on first run.
ADK surfaces all GhostCrab MCP tools as native Gemini function calls — no manual declaration.

Path 2 — BaseMemoryService backend (deep integration, cross-session)

from google.adk.runners import Runner
from google.adk.sessions import InMemorySessionService
from google.adk.tools.preload_memory_tool import PreloadMemoryTool
from ghostcrab_adk import MindBrainMemoryService  # thin wrapper package

runner = Runner(
    agent=agent,
    app_name="my_app",
    session_service=InMemorySessionService(),
    memory_service=MindBrainMemoryService(
        endpoint="http://localhost:8080"  # GhostCrab HTTP/SSE for deployed use
    )
)

search_memory() becomes a faceted ontology query.
add_session_to_memory() maps session events to typed ontology nodes.
PreloadMemoryTool injects relevant context before each LLM call — proactively,
without waiting for the agent to ask.

# Automatic ingestion at session end
async def auto_save_callback(callback_context):
    await callback_context.add_session_to_memory()
    # → MindBrainMemoryService persists typed entities, not raw text

agent = LlmAgent(
    model="gemini-2.5-flash",
    tools=[PreloadMemoryTool()],
    after_agent_callback=auto_save_callback,
)

→ Full configuration, skill files, and tested ADK walkthrough:
https://github.com/mindflight-orchestrator/ghostcrab-personal-mcp/blob/main/ghostcrab-integrations/google-adk/sop-google-adk-ghostcrab-mindbrain.md

https://github.com/mindflight-orchestrator/ghostcrab-personal-mcp/blob/main/ghostcrab-integrations/google-adk/skill_ghostcrab-runtime-adk.md

---

Differentiation vs native ADK memory options

Capability	InMemoryMemoryService	VertexAiMemoryBankService	VertexAiRagMemoryService	MindBrain via GhostCrab
Cross-session persistence	✗	✓ (cloud)	✓ (cloud)	✓ (SQLITE)
Structured / faceted search	✗	✗	✗	✓
Ontology-typed entities	✗	✗	✗	✓
Shared multi-agent context	✗	partial	partial	✓ (single registry)
Self-hosted / air-gap	✓	✗	✗	✓
Graph traversal	✗	✗	✗	✓

---

Scope of this request

• Adds GhostCrab MCP + mindBrain SQLITE (Personal edition) to the ADK integrations catalog
• No changes to ADK core agents, runners, sessions, or callback system
• No new required dependencies — MCPToolset integration requires only google-adk (already available)
• Cloud Run compatible: --memory_service_uri points to deployed GhostCrab endpoint; no Vertex lock-in

Repository	https://github.com/mindflight-orchestrator/ghostcrab-personal-mcp
License	Apache 2.0
Transport	stdio, CLI
Backend	SQLITE (bundled via mindBrain Personal)
ADK compatibility	google-adk Python SDK, BaseMemoryService interface
ADK integration type	BaseMemoryService + MCPToolset (no core modification)
Deployment	Local, Docker sidecar, Cloud Run