mushroomdb

mushroomdb is the data layer for agents that reason over entities. It is an embedded Rust graph database in which a relationship is a schema declaration: write a rule once, and every write derives, maintains and retracts the matching edges, each one carrying the rule, the score and the values that produced it.

What it does

You declare a rule once. mushroomdb evaluates it on every subsequent write and maintains the matching edges automatically — adding them when properties align, retracting them when they no longer do. The graph builds itself.

This is different from running a similarity script after each batch load or manually creating edges in a trigger. The rules are schema objects: they carry provenance, produce a score on each derived edge, and are queryable via the explain API and the bundled UI’s why panel.

Six predicate kinds ship today:

All six compose with All to require multiple conditions on the same edge.

Positioning

mushroomdb is embedded-first: it runs in your process, against a directory on disk, with no network round-trip and no server to start. The optional serve command adds an HTTP API and a bundled graph explorer when you want them, and several processes can share one store — see Concurrency.

ingest-git stays supported as a data source: commits, pull requests, files and authors become entities with rule-derived relationships, which is what makes a ticket↔commit link a rule rather than a script.

The benchmark numbers are in Benchmarks, and the architecture as built, with the roadmap, is in Architecture.

Status

Pre-1.0 alpha — APIs and formats may change between minor versions. Single writer, no multi-statement transactions. Toolchain pinned to Rust 1.92.0.

The current release is on the releases page. The shortest way in is the Claude Code plugin — claude plugin marketplace add MatthewSherlin/mushroomdb then claude plugin install mushroom@mushroomdb, and type /mushroom:mushroom in a repository. Or run npx mushroomdb install, which writes the /mushroom skill, the MCP server entry, and the session-start and prompt hooks for Claude Code or Cursor. The crates.io (cargo install mushroomdb-cli, cargo add mushroomdb) and PyPI (pip install mushroomdb) packages are published at the same version; which path gives you what is in the Install table.

Pages in this section

• Quickstart — a store, an assistant wired to it, and the four questions with one worked call each
• Concepts — how it works: stores, nodes, rules, explain, time, access, memory
• Rules — all six predicate kinds with examples
• API reference — which page covers which surface
• HTTP API — every route mushroomdb serve answers
• Python guide — the binding, with worked examples
• ingest-git as a data source — what ingest-git writes, its rules, submodules, pull requests, incremental sync
• Install — one row per way in, and what each leaves out
• Install, plugin and hooks — the two install routes, what each writes, and doctor
• MCP tools — the eleven task tools, the fourteen graph tools, and the twenty-three every store lists
• The association benchmark — one world in three forms, the twenty questions, and the gate
• Concurrency — many readers, one writer; the write lock, Busy, and refresh
• Node masks and access control — role tokens, client masks, restricted-stub mode
• Running it as a service — the volume, the snapshot interval, backup, restore, and what a restart costs
• Panic policy — which conditions panic vs. return a typed error
• Known limits — what it does not do, and what was measured
• Benchmarks — its own numbers, each with the file it comes from
• Architecture — the crates, the storage format, and the roadmap

Reference:

• CLI reference
• MCP tools — every tool with its arguments, generated from the server’s own listing
• Python API — every method of GraphDb, generated from the type stub
• Rust — embedding the engine: the types you touch, with examples that are compiled
• TypeScript client — the HTTP client: its methods, and the routes it leaves to fetch
• Cypher Query Reference
• Temporal history: what was connected when, and why
• Full-Text Search
• Vector search — similarity rules, find_similar, exact and approximate, the index
• Property (equality) indexes
• Graph Algorithms
• Materialized Property Views
• Live Subscriptions
• Rule Suggestion
• Durability and crash recovery
• Running several processes against one store
• Deployment
• Testing