# mushroomdb [Health: Active]

**Category:** 🗄️ Databases  
**Repository:** https://github.com/MatthewSherlin/mushroomdb  
**GitHub Stars:** 5  
**npm Downloads (last month):** 1712  
**Views:** 2  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/mushroomdb

## Description
Embedded graph database for agents: declare association rules once, edges maintain themselves.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "mushroomdb": {
    "command": "npx",
    "args": ["-y","mushroomdb"]
  }
}
```

## Documentation

## What mushroomdb does

The mushroomdb MCP server gives agents an entity store backed by an embedded graph database. Entities become nodes, while associations can be derived from shared values, foreign-key relationships, embeddings, geographic proximity, or other declared predicates. A rule is stored as part of the schema; later writes recalculate matching edges and remove edges whose supporting data no longer qualifies.

The store is intended for local agent memory. It keeps facts, relationships, similarity results, and lineage in a directory on disk without requiring an account, hosted endpoint, or model call during writes unless embeddings are enabled. The project is pre-1.0, so APIs and formats may change between minor versions.

## How it works

Agents can write notes with `remember`, search indexed text with `recall`, and inspect structured graph data with `query`. `suggest_rules` can identify repeated field values that may justify a relationship rule, but a proposed rule is not activated until `create_rule` approves it. Once active, the rule participates in subsequent writes.

Relationship inspection is a central use case. `explain_association` reports the rule, score, predicate, and values that support a link. `node_edges` and `neighborhood` list related nodes, while `edges_at` reconstructs the relationships a node had on a past date or commit index. `what_if` calculates edges that a proposed property change would add or remove without modifying the store.

The server also supports full-text and vector-oriented retrieval. `find_similar` can search by a query vector or by a rule-derived edge type, `hybrid_search` combines full-text and vector rankings, and `pairwise_similar` compares a caller-provided set of keys without using HNSW. `find_similar` uses a default minimum threshold of 0.8 on every interface.

## Setup and configuration

Install the local MCP setup with:

```sh
npx mushroomdb install --db ./memory
```

The command creates the `/mushroom` skill, configures an MCP server exposing the association surface, and writes session hooks. The MCP command can list the task-oriented tools first with `mushroomdb mcp <db> --all-tools`.

The database can also be used as a Rust library, Python module, or sidecar. `ingest-git` remains available as a data source for commits, pull requests, files, and authors. Schema files can be applied idempotently with `mushroomdb schema apply <dir> <schema.json>`, including rules, views, and full-text indexes.

## Tools and capabilities

The mushroomdb MCP server exposes twenty-three tools on its entity store. Notable capabilities include:

- Write notes and provision unknown referenced entities with `remember`.
- Retrieve ranked free-text matches with `recall`.
- Query graph structure using Cypher through `query`.
- Explain rule-derived links with supporting evidence.
- List node edges, neighborhoods, and historical edges.
- Preview relationship changes with `what_if`.
- Apply per-call masks or scoped, read-only handles with roles, namespaces, and key restrictions.
- Load nodes and edges atomically with conflict handling through `ingest_batch`.

HTTP role tokens provide the actual enforcement boundary for access control; in-process scopes and masks are cooperative argument handling rather than security isolation.

## Limitations and notes

The project is explicitly alpha and may change between minor releases. The former code-graph interface was removed in version 0.7; applications that need it must use the 0.6.x line. Historical queries depend on recorded timestamps or commits: a store without timing information reports that fact instead of guessing. The local setup is not, by itself, a remote authorization boundary.

_Full upstream README: https://allmcps.com/mcp/mushroomdb/readme_