ARCHITECTURE

What GhostCrab
actually is.

GhostCrab is an open-source MCP server that gives AI agents a structured world to navigate.
It sits between your agent and mindBrain, exposing a practical working surface
for records, documents, dependencies, procedures, goals, constraints, and long-running project state.

GhostCrab does not replace your agent. It gives your agent a better environment to work in.

INSTALL ON GITHUB SEE A REAL EXAMPLE

Hello, I'm GhostCrab — your favorite MCP server.

GhostCrab sits between your agent and mindBrain.

It helps the agent find the right slice of a project, follow what connects,
and pull a compact working context for the task at hand.
That is the architectural idea in one line.

WHAT YOU INSTALL

Not a chat app. A working layer.

When you install GhostCrab, you are installing an MCP-friendly server layer that lets
your existing agent work with structured project state on mindBrain
(Personal on SQLite, or Professional on PostgreSQL).

Your agent

Remains the interface — reasoning, conversation, intent.

GhostCrab

Exposes tools and structure — retrieval, relations, context.

mindBrain

Provides durable structured storage underneath — SQLite for Personal, PostgreSQL for Professional.

If you already use Claude Code, Cursor, Codex, or OpenClaw, GhostCrab extends that setup — it does not replace it.

SEE SUPPORTED USE CASES

THE MENTAL MODEL

3 capabilities. 1 MCP surface.

Find

The agent needs to narrow a large project or domain to the relevant subset.

Facettes

Follow

The agent needs to understand relationships, blockers, prerequisites, and missing links.

Graphes

Pack

The agent needs a compact, useful working bundle — not a transcript dump.

Projections

THE THREE LAYERS

Facettes

How the agent finds the right slice of a domain.

Roaring Bitmaps · Hybrid BM25 + embeddings · Millisecond filtering on large collections (mindBrain Professional — PostgreSQL)

Filter by status, owner, country, regulation, project, phase, priority, customer, or role.
The point is not just "search." The point is that the agent does not have to reread everything
to locate one relevant subset.

Example questions

→ Which onboarding cases are blocked in Belgium?
→ Which deals are in negotiation with no legal review yet?
→ Which tasks are still open for this project phase?

Graphes

How the agent understands dependencies, blockers, and missing knowledge.

REQUIRESBLOCKSVALIDATESDEPENDS_ON

Direction matters. A → B is not the same as B → A.
Professional domains are full of asymmetric relationships: legal procedures, diagnostic protocols,
onboarding workflows where prerequisites only make sense in one direction.

A flat list can tell the agent what exists. A directed graph helps the agent understand what must happen first, what is blocking what, what can be skipped, what requires escalation, and what is still missing from the current model.

Projections

How the agent gets a compact working context for the current task.

FACT GOAL STEP CONSTRAINT

Not a transcript. Not a replay. Not a raw graph dump.
A ranked bundle of the right FACT · GOAL · STEP · CONSTRAINT — pre-ranked,
preformatted, with provenance attached. Typically 80 to 200 bytes.

Even if the project is perfectly modeled, the agent still cannot dump all of it into the model context and expect good reasoning. Projections give the agent a usable reasoning surface for the current turn.

PERFORMANCE

Enterprise-grade performance, not just better prompts.

GhostCrab is not a thin memory layer sitting on top of an agent.
It is the working interface to a real agentic database.
Traversing dependencies, blockers, prerequisites, and directed relationships in Graphes
is designed to stay in the same practical performance range, so the agent can follow structure at speed
instead of treating graphs like slow decorative metadata.

~4.3B

documents per table (Roaring Bitmaps on 32-bit IDs) — mindBrain Professional

Millisecond

filtering latency on tens of millions of documents — mindBrain Professional

Projections

pre-pack the working context — no cold-start search required

GhostCrab works with two versions of mindBrain:
mindBrain Personal (SQLite) — lightweight, single-file, zero infrastructure, for individuals and small teams.
mindBrain Professional (PostgreSQL) — enterprise-grade, high-throughput, production-ready, for organizations.
Together, GhostCrab and mindBrain form a complete agentic data system — from personal projects to enterprise operations.
Not just a vector-only search layer. Not just a graph-only engine.
Not just a workflow wrapper. A full structured foundation for agents that need
retrieval, relationships, and ready-to-use working context in one coherent stack.

DIVISION OF LABOR

GhostCrab vs. the agent.

GhostCrab provides the structured working surface.

→ records
→ documents
→ states
→ relations
→ dependencies
→ procedures
→ constraints
→ context packs

It makes the project navigable.

The agent remains the reasoning and conversational layer.

→ asks setup questions
→ interprets intent
→ decides what to inspect
→ explains blockers
→ asks follow-up questions
→ proposes next actions
→ helps move the work forward

GhostCrab gives that intelligence a map, a memory shape, and a set of reliable handles.

ONE REQUEST, STEP BY STEP

What happens when an agent uses GhostCrab?

Show me what is blocking onboarding for new hires in Belgium.

Facettes

Narrows the field

Filters to the relevant hires, tasks, documents, statuses, and owners. Instead of scanning everything, the agent starts from the right slice.

Graphes

Follows the structure

Traverses REQUIRES, BLOCKS, VALIDATES, DEPENDS_ON. Now the agent sees not just what exists, but what is connected, what is blocked, and what prerequisite is missing.

Projections

Packs the working context

Returns the most relevant FACTS, GOALS, STEPS, and CONSTRAINTS for this exact question. The model sees the useful surface, not the whole substrate.

The agent responds

→ Which onboarding cases are blocked
→ What is missing
→ What should happen next
→ Which owner needs to act
→ What follow-up question should be asked

SEE THE FULL ONBOARDING WALKTHROUGH

WHY THIS EXISTS

Most agent failures come from the same pattern.

✗ too much raw context
✗ too little structure
✗ no explicit dependencies
✗ no clear separation between source data and working context
✗ no durable project state the agent can actually navigate

The agent needs not only access to information, but a structured model of what it knows,
what it does not know, and what should be surfaced right now.
Facettes, Graphes, and Projections are three distinct roles in one coherent stack.

GhostCrab turns that architecture into something an MCP-capable agent can actually use.

WHY NOT CHAT HISTORY

Long transcripts are not a working model.

Chat history can preserve words. It does not reliably preserve structure.
A real project usually contains entities, states, rules, dependencies, blockers,
procedures, and evolving context.
If all of that lives only in prose, your agent has to reconstruct the project over and over again.
That is wasteful, brittle, and easy to break.

Chat history

→ preserves words
→ hard to filter
→ degrades with length
→ no dependency model

GhostCrab

→ faceted retrieval
→ directed relations
→ typed working context
→ durable project state

FAQ

Is GhostCrab a server, a framework, or a concept? +

GhostCrab is an MCP server layer for structured agent work. Not just a concept. Not just a schema idea. The practical bridge between your agent and a structured mindBrain-backed project model.

What exactly sits under the hood? +

One MCP surface over three mindBrain capabilities — Facettes for retrieval and filtering, Graphes for directed relationships and dependency gaps, Projections for compact typed context packs.

Does GhostCrab store state? +

Yes. The architecture is built around durable project structure and canonical sources in the structured database, while Projections stay projection-only rather than becoming a second source of truth.

Does GhostCrab do the reasoning? +

No. Your agent still does the reasoning. GhostCrab provides the structure the agent works with.

Is GhostCrab only for technical workflows? +

No. The architecture is useful whenever a domain has entities, stages, dependencies, rules, and evolving state — onboarding, CRM, compliance, project coordination, research, personal planning.

GhostCrab gives your agent more than context.

It gives it structure.

Find what matters. Follow what connects. Pack the right working surface.

INSTALL ON GITHUB SEE USE CASES

Hello, I'm GhostCrab — your favorite MCP server.