Fushiguro

An MCP server that routes a task to the right specialist agent, assembles everything that agent needs to do it well, and remembers how you want work done.

It is built to be dropped into any business adopting AI. The packaged catalog gives you a working set of agents, skills, tools, connectors, topics, and runbook templates on day one; your own catalog layers on top of it without forking anything.

What it does

Call one tool, brief, with a task. It first decides how much delegation the task deserves, which is as much about spending less as spending more:

Wrapping a one-line fix in a four-stage pipeline burns tokens and adds latency for nothing, so the triage refusing to delegate is a feature, not a fallback.

For anything it does delegate, you get a system prompt ready to hand to a subagent, assembled from:

• the right agent for the task, chosen by a router that improves as you correct it

• the skills that apply — reusable procedures like citation discipline or data-quality checks

• the runbooks that govern this kind of work, with their owners and escalation conditions

• retrieved knowledge from your own documentation, cited by chunk id

• the tools and connectors it may use, with the guardrails on each

• your standing preferences, learned over previous sessions

The host spawns the subagent. Fushiguro never calls a model itself, so there is no API key and no separate bill — it runs on whatever session you already have.

Related MCP server: DriftOS MCP Server

Install

Requires Node 22.5+. It uses the built-in node:sqlite, so nothing compiles and the whole package is 80KB.

Try it

npx -y fushiguro-mcp --help

Register it with your host

For Claude Code, the scope decides who gets it:

# Just you, just this project
claude mcp add fushiguro -- npx -y fushiguro-mcp

# Just you, every project you open
claude mcp add fushiguro --scope user -- npx -y fushiguro-mcp

# Your whole team — writes .mcp.json, which you commit
claude mcp add fushiguro --scope project -- npx -y fushiguro-mcp

For any other MCP host, the equivalent config block:

{
  "mcpServers": {
    "fushiguro": {
      "command": "npx",
      "args": ["-y", "fushiguro-mcp"],
      "env": { "FUSHIGURO_CATALOG": "/absolute/path/to/your/catalog" }
    }
  }
}

From source

git clone <this repo> && cd Fushiguro-mcp-mem
npm install && npm run build && npm test
claude mcp add fushiguro -- node "$PWD/dist/index.js"

Setting it up for a business

cd your-repo
npx -y fushiguro-mcp init          # scaffolds .fushiguro/catalog

Then, in rough order of payoff:

1. Knowledge first — this is the highest-leverage step by a wide margin. Put your real policy and product documents in knowledge/<collection>/. Everything else is scaffolding around this. Without it, agents are generic; with it, they cite your actual refund policy.

2. Describe your connectors and delete the packaged ones you do not use. Record env var names, never secret values.

3. Fill in one runbook — escalation is usually the one that hurts most today. Set template: false when done.

4. Extend one agent with your house rules, or add a role the base set does not cover.

5. Commit the catalog. It is a shared business asset, and it belongs in version control like any other.

Run the status tool at any point to see what loaded and what is still an unfilled template.

Sharing it across a business

The server is just a runtime — the catalog is the thing worth sharing. Three topologies, by org size:

One team, one repo

Commit .fushiguro/catalog/ and a project-scoped .mcp.json to the repo. Anyone who clones it is prompted to enable the server and gets the catalog automatically. Nothing to install, nothing to configure.

npx -y fushiguro-mcp init
claude mcp add fushiguro --scope project -- npx -y fushiguro-mcp
git add .fushiguro .mcp.json && git commit -m "Add AI catalog"

Several teams, many repos

Keep the catalog in its own repo — acme-ai-catalog — so one set of policies, runbooks, and agents serves every project. Clone it once per machine and point the server at it:

{ "env": { "FUSHIGURO_CATALOG": "/Users/you/work/acme-ai-catalog" } }

Or vendor it into each repo as a git submodule, so a project pins a known-good catalog version. Changes go through pull request, which is the point: a change to an escalation path or a refund policy should be reviewed like a change to code.

Larger organisations

Publish the catalog as a private npm package (@acme/ai-catalog) and depend on it. You get versioning, a changelog, and staged rollout — teams upgrade when they choose rather than being moved underneath. Point FUSHIGURO_CATALOG at node_modules/@acme/ai-catalog.

You can also publish a fork of the server itself with your catalog baked in as the base layer, so npx @acme/ai is the entire setup for a new hire.

What is shared and what is not

This distinction matters, and it is the one people get wrong:

A rule that applies to everyone belongs in the catalog, where it is reviewable and versioned. A preference that is one person's working style belongs in memory, captured through remember. Putting an org policy in memory means only one person's agent follows it — and nobody can see that it exists.

Memory is per-user by design. There is no shared memory database, and adding one would let a single person's habit silently become everyone's policy without review.

The catalog

Seven kinds of entry, each a markdown file with YAML frontmatter.

Two layers, merged

Entries shipped with the package are base. Entries in your own catalog are custom. When both exist under one name they merge into base+custom: your scalar fields win, list fields union, and your body is appended under an "Organisation-specific additions" heading.

---
name: customer-support     # same name as a base agent
model: opus                # overrides the base model hint
keywords: [overage, seat]  # added to the base keywords
connectors: [acme-helpdesk]
---

## Acme specifics

Acme sells three plans. Entitlement differs sharply between them...

That is the whole customisation. You keep receiving improvements to the base prompt underneath your additions. Set override: true in your frontmatter to replace the base body outright instead.

Every listing tags each entry [base], [custom], or [base+custom], so it is always clear what is in play.

See examples/acme-corp/catalog/ for a worked custom catalog.

Runbooks are templates

The packaged runbooks are process templates, not policy. Their structure is the general shape of the process; the owners, thresholds, and escalation paths are decisions your business has to make.

Every unmade decision is marked [FILL: ...]. While a runbook still has template: true, agents are told to treat it as guidance and to refuse to invent values for the gaps rather than proceeding as though a policy existed. Once you have filled it in, set template: false.

status lists every runbook still awaiting completion, with a count of remaining fields.

Start from catalog/runbooks/_TEMPLATE.md, copy it to .fushiguro/catalog/runbooks/, and fill it in. The section that pays for itself is Decision points — the places where the answer is a judgement rather than a lookup. Those are exactly where an agent must stop and hand over.

Memory

Memory is separate from the catalog: the catalog is what your organisation configured, memory is what the system learned about how this user wants work done.

remember("Never quote a renewal date from memory", kind: "constraint", agent: "customer-support")

Five kinds, and they are not equal:

• constraint — a hard rule

• correction — fixing a past mistake

• preference / style — a soft taste

• fact — context about the user or business

Behaviour that follows from that:

• Restating reinforces, it does not duplicate. Saying the same thing in different words updates the existing memory and raises its confidence.

• A constraint retires the softer memory it contradicts, keeping the trail rather than leaving both to fight.

• Constraints and corrections are always injected, whether or not they match the task's wording. A rule that only surfaces when you happen to use the same word is not a rule.

• Scope: global follows you everywhere, project is keyed to one codebase or workspace.

Delegation and pipelines

The triage

Complexity is scored from the shape of the request: creation verbs (build, implement) against change verbs (fix, add), whole-system nouns (website, platform), open-ended scope (from scratch, production-ready), how many specialists credibly match, question phrasing, length, and conjunction count. The score, the bucket, and every signal are returned, so the decision can be argued with rather than trusted:

PIPELINE — 4 stages. Assessed complex (score 5): produces an artifact (create);
whole-system noun (website); a whole system to be built, not a change to an
existing one; spans two specialisms.

Override it any time with mode: "handle_directly" | "single_agent" | "pipeline".

The stages

Agents declare which positions they can fill via roles: [planner, executor, tester, reviewer]. The routed specialist always takes executor — it was chosen for the subject matter — and the other positions go to the best-scoring agent declaring that role. A reviewer is never the same agent as the executor, because reviewing your own work is not reviewing.

Each stage's prompt states its role, what it receives, and what it must hand on, with an instruction to stay inside that role: a planner that starts implementing produces work the executor will redo differently, and that hides the disagreement rather than settling it.

brief composes only stage 1. Fetch each later stage with get_stage, passing the previous stage's output as context — later stages are briefed on what they are actually receiving, and you never pay for prompts you may not use.

Intake questions

Agents declare intake: questions to put to the user before work of that kind starts. "Create a booking website for a dental clinic" is missing a great deal — platform, existing stack, integrations, whether it handles personal data.

Questions the request already answers are dropped, so answering in the first message means you are not asked again. Asking about a stack the user already named is the fastest way to get an intake step ignored entirely.

Installing skills from the ecosystem

There is a growing body of open Agent Skills, and this reads that format directly. Seven collections are curated in:

fushiguro-mcp skills                          # what is available
fushiguro-mcp skills show emil-kowalski       # what is in one
fushiguro-mcp skills add emil-kowalski        # install all of them
fushiguro-mcp skills add jakub-krehel better-typography better-layout

All MIT licensed. Nothing is vendored into this package — installing fetches from the author's repository, so they keep authorship and you get the current version rather than a fork frozen at whenever this was published. Each installed skill carries a _SOURCE.md recording its origin, licence, and fetch date.

Between them these sources offer around 270 skills. Install selectively: skills are chosen per task, but a catalog of hundreds makes that choice noisier and gives you more to review. Start with the handful matching work you actually do.

Set GITHUB_TOKEN if you install several collections in one sitting — unauthenticated GitHub allows 60 requests an hour.

How they fit

A folder containing SKILL.md is one skill; the files beside it are resources it references, not separate entries. Skills in that format declare only name and description, so keywords are derived from those — without that they would sit below the selection floor and never attach to anything.

Installed skills land in your custom catalog, so they merge and layer like anything else you write.

Conversation threads

A long conversation about one subject costs its full length on every subsequent turn. Switch topic and you keep paying for context nobody is using.

What this server cannot do: clear your context. No MCP server can — none of them has access to your conversation window. Only you can run /clear.

What it does instead is make clearing safe, by remembering the subject for you:

User has been working on a booking site, then switches subject.

brief → NEW TOPIC — this does not look like a continuation of
        "Dental clinic booking site" (similarity 0).
        To save tokens: summarise what was covered and call `save_thread`,
        then tell the user they can run /clear.

... much later, the subject comes back ...

brief → RESUMES thread #1 "Dental clinic booking site" (score 1) —
        you discussed this before. Context recovered:
          Building a booking site for a dental clinic. Next.js + Postgres,
          Google Calendar sync for slots.
          Decided:
            - Next.js + Postgres
            - Google Calendar for availability
          Still open:
            - Which payment provider?

The decisions are the part that matters. A cleared conversation loses the reasoning, and re-deriving "why Postgres" costs far more than storing the sentence.

brief reports one of three relations on every call: continues the current subject, new subject, or resumes an older one. Topic matching uses the same keyword-and-semantic machinery as knowledge retrieval, so "the clinic appointment app" finds a thread titled "Dental clinic booking site".

Tools: save_thread, recall_thread, resume_thread, forget_thread.

The thresholds lean toward staying put. Wrongly declaring a new topic suggests clearing context that was still useful; wrongly missing one just means the conversation runs a bit long. The first mistake is much more expensive, so FUSHIGURO_SAME_TOPIC defaults low (0.25).

Summaries are written by the host, not this server — it cannot see your conversation, so it cannot summarise it for you.

Retrieval: keyword and semantic

By default search_knowledge uses BM25 — keyword matching. That fails on a question phrased differently to the document that answers it:

Asked: "how long do I have to get my money back on the yearly plan" Document: "Annual: pro-rated refund within 30 days of the initial charge."

Not one meaningful word in common. Enabling embeddings turns retrieval hybrid: both retrievers run, and results are fused by rank.

Enabling it

npm install @huggingface/transformers    # local model, no key, no bill

That is the whole setup — the server detects it and starts embedding. Or use a hosted embedder instead, which needs no install:

export VOYAGE_API_KEY=...     # or OPENAI_API_KEY

FUSHIGURO_EMBEDDINGS takes auto (default — hosted key if set, else local if installed, else off), local, voyage, openai, or off.

The model runtime is deliberately not a dependency. It is ~390MB, and a business that only needs keyword search should not pay for it. Without it, the package stays under 100KB and retrieval works exactly as it did before.

What it does and does not fix

Measured against the sample corpus with all-MiniLM-L6-v2:

Both halves matter. A small embedding model is noise on exact tokens — error codes and plan names score ~0.07 against everything — and it blurs discriminating detail, ranking the Starter passage above the Annual one for an annual-plan question. BM25 is precise about exactly those. Neither retriever is good enough alone, which is why this fuses rather than replaces.

Fusion is Reciprocal Rank Fusion on rank, not score. BM25 scores and cosine similarities are incomparable scales, and normalising between them means a fudge factor that needs retuning whenever the corpus changes.

Operationally

Embedding runs in the background. The first run downloads a model (~90MB, roughly 80 seconds), and during that time searches are keyword-only — a worse answer, never a hung tool call. status reports which mode is live, and every result says which retriever found it (keyword, semantic, or keyword+semantic).

Vectors are cached in the same SQLite file and reused across restarts. Changing model or corpus re-embeds rather than mixing incompatible vector spaces. Search is brute-force cosine over normalised vectors — 3ms on a small corpus, and fine into the low tens of thousands of chunks.

How routing works

Each agent is scored on: keyword matches weighted by how distinctive the keyword is across the catalog (IDF), hand-written regex patterns, similarity to its example triggers, whether a matched topic vouches for it, and how past outcomes for those terms have gone.

That last signal is what improves with use. After a task, call record_outcome:

record_outcome(task: "...", agent: "docs", outcome: "wrong_agent", correct_agent: "process-automation")

This reweights the term-to-agent affinities, so your business's own vocabulary — an internal system name, a product codename — starts routing correctly without anyone adding it as a keyword.

When the top two agents score within 85% of each other, the briefing says so instead of picking silently. When nothing scores above the floor, it says that too rather than forcing a match.

Tools

Also exposes the delegate prompt and a fushiguro://catalog resource.

Command line

fushiguro-mcp              Start the MCP server on stdio (what a host runs)
fushiguro-mcp init [dir]   Scaffold a business catalog, safe to re-run
fushiguro-mcp skills       List curated skill collections
fushiguro-mcp skills show <source>
fushiguro-mcp skills add <source> [skill...] [--force]
fushiguro-mcp --help

Configuration

Catalog files are re-read when they change on disk, and the knowledge index rebuilds when the corpus hash changes — edit an agent or a policy document and the next brief picks it up without a restart.

Limitations, stated plainly

• Retrieval is keyword-only until you enable embeddings, and a keyword search misses passages phrased differently to the question. With them enabled it is hybrid, but a small local model still blurs the details that distinguish two similar passages — see the table above. A hosted embedder is meaningfully better on domain jargon.

• Topic detection is a similarity score, not comprehension. A task that changes subject while reusing the old vocabulary reads as a continuation; a genuine continuation phrased in fresh words can read as new. Both thresholds are tunable, and the similarity is always reported so the call can be second-guessed.

• Vector search is brute force. Every query scores every chunk. That is milliseconds up to the low tens of thousands of chunks and will not scale past that without a real vector index.

• Complexity assessment is lexical. It reads the shape of the request, not its meaning. An innocuous-sounding sentence hiding a quarter of work will be under-scored, and a verbose request for something small will be over-scored. The signals are always shown and mode always overrides.

• Routing is lexical too, plus learned outcome weights. It has no understanding of the task; it matches configured signal. A catalog with thin keywords routes badly, and the fix is better keywords and more record_outcome calls.

• Deduplication of memories is lexical. Two preferences that overlap heavily in wording but differ in object may merge. Requiring three shared distinct tokens keeps this rare, not impossible.

• The host executes everything. Fushiguro assembles and returns prompts; it never calls a model, never spawns a process, and never reaches a connector itself.

Layout

src/
  index.ts       launcher and CLI (server | init | --help)
  init.ts        scaffolds a business catalog
  complexity.ts  triage: how much delegation a task deserves
  main.ts        stdio transport and lifecycle
  server.ts      MCP tool, prompt, and resource surface
  catalog.ts     loads and layers the seven entity kinds
  router.ts      scoring, selection, and prompt composition
  memory.ts      preferences, reinforcement, outcome learning
  knowledge.ts   chunk index, hybrid retrieval, rank fusion
  embeddings.ts  pluggable embedding providers (local, voyage, openai)
  threads.ts     conversation topics, continuity detection, resumption
  skill-sources.ts / skill-install.ts / skills-cli.ts
                 curated ecosystem skill collections and their installer
  text.ts        tokenising and similarity helpers
catalog/         the packaged base catalog
examples/        a worked custom catalog, and an .mcp.json template
test/smoke.mjs   end-to-end checks over the real catalog