mushroomdb

The graph that stays true — and knows who's allowed to see it.

An embedded Rust graph database where edges are a schema declaration: write a rule once, and every write creates, maintains, and retracts the matching edges. Ships a 24-tool MCP server and a live graph of the repository it is pointed at.

Pre-1.0 alpha — APIs and formats may change between minor versions.

Docs · Changelog · Issues

Quick start

Install the Claude Code plugin, from any directory:

claude marketplace add MatthewSherlin/mushroomdb
claude plugin install mushroom@mushroomdb

Open the repository you want graphed and type /mushroom:mushroom. The skill builds the graph on first use and answers with it from then on.

Or install into one project (or your home directory) without the plugin — same skill, invoked bare as /mushroom:

npx mushroomdb install    # /mushroom skill + MCP server + prompt, post-edit and git hooks

Either way, the first thing the assistant does is read the repository back to you. This is a real run against this repository — ingest-git took 2.5 s, map 0.18 s:

mushroomdb map — 431 files, 6,226 symbols, 652 commits, 2 authors · synced 3s ago at 94719fe
clusters (co-change + imports)
  1. <mixed> crates, tests  (86 files, cohesion 0.73)  crates/server/tests/http.rs, algo.rs, crates/server/src/http.rs
  2. <mixed> crates, src  (45 files, cohesion 0.67)  pack.rs, lib.rs, types.rs
  3. ui src, e2e  (26 files, cohesion 0.89)  api.ts, store.ts, classify.ts
  4. crates/code-extract tests, fixtures  (21 files, cohesion 0.99)  lib.rs, extract.rs, mod.rs
  5. ui fonts, public  (18 files, cohesion 0.89)  IBMPlexMono-Medium.woff2, IBMPlexMono-Regular.woff2, IBMPlexSans-Medium.woff2
  6. crates/core-api src, repograph  (17 files, cohesion 0.72)  facts.rs, render.rs, context.rs
  7. <mixed> crates, bindings  (16 files, cohesion 0.99)  crates/core-bench/Cargo.toml, package.json, crates/sim-harness/Cargo.toml
  8. benchmarks adapters, results  (15 files, cohesion 1.00)  run_handrolled.py, datasets.py, handrolled.py
key files (most depended-on)
  crates/code-extract/src/lib.rs 0.05 · crates/server/tests/http.rs 0.04 · crates/code-extract/tests/extract.rs 0.04 · crates/core-api/tests/algo.rs 0.04 · crates/server/src/http.rs 0.03
owners
  Matthew Michael Sherlin 431 files
hot (last 90 days)
  crates/core-api/src/db.rs 175 · README.md 109 · crates/core-rules/src/engine.rs 56 · crates/core-query/src/cypher/exec.rs 54 · crates/cli/src/lib.rs 51
ask me: why does lib.rs co-change with extract.rs? · who owns ui? · what imports http.rs?

From there: context for one file or symbol from every side, impact before an edit, owners, why with the commits that prove a link, recall and remember for durable notes. Full walkthrough: docs/site/code-graph.md.

• Live, not a snapshot. One SET f.top_author_id = … moves the TOP_AUTHOR edge and re-derives that author's KNOWS edges before the write closes — the SET in the GIF above is that one write. An editor hook does the same for your code: touch re-extracts an edited file after every Edit, Write and MultiEdit, in about 180 ms on this repository's graph.
• Retracts instead of going stale. Re-run ingest-git to sync: only new commits replay, deleted files drop their derived edges, and renamed files carry their history to the new path.
• Explains any link. explain names the rule and the score behind an edge, so "which files change together with src/api.rs, and why?" has an answer your assistant can quote instead of a guess.
• Knows who's allowed to see it. Pass a mask with a query and the same graph answers differently per caller; write statements are rejected on masked queries.
• Answers what it said last week. mushroomdb asof ./db --commit 5 --query "…" replays the WAL to a past commit, derived edges included.

Where it fits

What it is

• An embedded, single-binary graph database with a rule engine that maintains edges for you.
• A 24-tool MCP server plus a /mushroom skill and a Claude Code plugin.
• Safe for several processes at once: one writer at a time behind an advisory LOCK file, any number of readers, and every handle picks up a peer's commits by refresh() rather than reopening — so a running serve, an editor hook, a git hook and a CLI command can share one store. docs/site/concurrency.md
• Local-first: your data stays on disk, no cloud service, no LLM in the write path.

What it isn't

• Not a hosted memory service — there is no account, no endpoint, nothing to sign up for.
• Not a vector database. Vector predicates and HNSW are built in; bring your own embeddings.
• Not a Postgres replacement. Single writer, no interactive transactions, memory-first storage.

The differentiator

Most graph databases require you to create edges manually or run a batch similarity script after each load. mushroomdb makes edge creation a schema declaration. A rule like "connect every Person to every Org whose skills list overlaps theirs by at least 50%" is written once:

db.create_rule(RuleDef {
    name: "skill_fit".into(),
    src_label: "Person".into(),
    dst_label: "Org".into(),
    predicate: Predicate::Overlap { field: "skills".into(), min: 0.5 },
    edge_type: "FIT".into(),
    weight_prop: Some("score".into()),
    max_edges: Some(5), // keep the 5 best-matching Orgs per Person (top-k per source)
}).expect("rule");

After that, every insert_node and set_prop evaluates the rule incrementally. The engine writes the edge, stores the Jaccard score, and retracts the edge if the properties later diverge — without any manual work.

Watch it live — a Cypher SET changes one property, the founded_within rule fires, and new scored edges appear in the bundled explorer:

Open the Rules panel, and the Why slide-over shows the exact predicate arithmetic behind every derived edge:

Predicates

Six predicate kinds ship today. They compose via All(...) (AND, score = min) and Any(...) (OR, score = max), nested up to depth 4.

Auto-FK: fields ending in _id whose values match existing node keys get KeyMatch rules created automatically at ingest time. VectorSimilar accepts approximate: true to switch candidate selection to in-tree HNSW (per-query recall min 0.90, mean 0.998 at 5k nodes / dim 1536, fixed-seed probe). Full reference: docs/site/rules.md.

Built on the same engine

• Live subscriptions. subscribe_rule (Rust) and GET /subscribe (WebSocket) stream EdgeFired / EdgeRetracted the moment they hit the WAL — not polled, not batched. Bounded 65,536-event queue; slow consumers get a Lagged { missed: N } marker instead of a disconnect. docs/site/subscriptions.md
• Rule attribution across time. Every derived edge writes a HISTORY-MARKER WAL record carrying the rule name, so edge_history, node_history, and was_linked answer which rule created a link and at which commit. GraphDb::open_at(&dir, 5) replays to a past commit, derived edges included; out-of-range commits return CommitOutOfRange, never wrong data. docs/site/timetravel.md
• Materialized views. Degree counts and neighbor aggregates (sum/avg/min/max) maintained incrementally on every edge change — no cron, no triggers, no stale caches. docs/site/views.md
• Rule suggestions. db.suggest_rules() (or mushroomdb suggest ./db) profiles your data and ranks candidate rules with estimated edge counts and rationale. Seeded sampling, so the same database always returns the same suggestions. No rule is ever applied automatically. docs/site/suggest.md

Agent memory

Graph structure captures the shape of real knowledge — entities, associations, similarity, and lineage — and rule-derived edges keep those associations fresh as new facts arrive.