mushroomdb (Python)

Python bindings for mushroomdb — the embedded graph database where edges are declared, not inserted.

import mushroomdb

db = mushroomdb.GraphDb.open("./db")
db.insert_node("Org", "org-01", {"founded_year": 2010})

GraphDb.open creates the directory if it does not exist. The handle is also a context manager, so with mushroomdb.GraphDb.open("./db") as db: closes on exit.

Writing nodes

db.insert_node("Person", "alice", {"team": "red"})   # raises if 'alice' exists
db.upsert_node("Person", "alice", {"team": "blue"})  # "inserted" or "updated"
db.set_prop("alice", "team", "green")
db.set_prop("alice", "team", None)                   # same as remove_prop
db.remove_prop("alice", "team")                      # False if already absent
report = db.delete_node("alice")                     # {"manual_edges", "derived_edges"}

upsert_node writes only the fields you pass whose value differs from the stored one. Fields you omit are left alone, and unchanged fields produce no WAL record, so rules do not re-fire needlessly. An existing key under a different label raises ValueError — relabelling is not an upsert.

Querying

query and query_write both accept parameters as a dict, as a list of (name, value) tuples, or not at all. Parameters are bound, never interpolated into the Cypher string.

rows = db.query(
    "MATCH (n:Person) WHERE n.age > $min RETURN key(n) AS id",
    {"min": 18},
)
db.query_write(
    "MATCH (n:Person) WHERE key(n) = $k SET n.age = 31 RETURN key(n)",
    {"k": "alice"},
)

A node's key is not a property, so n.key does not resolve. Use the key(n) scalar function to project or filter on it. node_info returns the key too.

Rules

db.create_rule({
    "name": "same_team",
    "src_label": "Person",
    "dst_label": "Person",
    "predicate": {"kind": "field_equal", "fields": ["team"]},
    "edge_type": "SAME_TEAM",
    "weight_prop": None,
})

The canonical predicate shape is snake_case — {"kind": ..., "fields": [...]} plus whatever numeric knob the kind takes (min, tolerance, km, or parts for all/any). This is exactly the shape explain emits, so an explanation round-trips straight back into a new rule:

why = db.explain("alice", "bob")
clone = {**base, "name": "same_team_clone", "predicate": why[0]["predicate"]}
db.create_rule(clone)
kind extra keys
key_match, field_equal —
overlap, vector_similar min
numeric_within tolerance
geo_radius km
all, any parts (a list of nested predicates)

The Rust-native externally-tagged form is still accepted: {"FieldEqual": {"field": "team"}}, {"Overlap": {"field": "skills", "min": 0.5}}.

create_rule returns True when it created the rule. Pass if_not_exists=True to get False instead of an exception when a rule of that name is already registered.

Concurrency

One writer process per store. There is no cross-process lock yet (planned); opening the same directory from two processes that both write can corrupt it. Keep writes in a single process.

A handle sees only the commits made through it. It does not poll the store, so writes made by another process after you opened are invisible to your handle. To pick them up, close and open again — there is no reopen():

db.close()
db = mushroomdb.GraphDb.open("./db")

Within one process the handle is guarded by a mutex, so calls from multiple threads are serialized and safe. They are not isolated transactions: readers can observe intermediate states while a batch is being applied.

Type stubs

The wheel ships __init__.pyi and a py.typed marker, so mypy and Pyright pick up signatures without extra configuration.

Full documentation, the rules tour, and benchmarks live in the main repository.

Project links

Data verified by PyPI on Sep 3, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for nilrehsttam from gravatar.com nilrehsttam

GitHub Statistics

Data verified by PyPI on Sep 3, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

Apache Software License (MIT OR Apache-2.0)

Requires

Python >=3.10

Tags

graph embedded database mcp agent-memory hnsw association

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

mushroomdb-0.5.2-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (2.2 MB view details)

Uploaded CPython 3.10+manylinux: glibc 2.17+ x86-64

mushroomdb-0.5.2-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (2.0 MB view details)

Uploaded CPython 3.10+manylinux: glibc 2.17+ ARM64

mushroomdb-0.5.2-cp310-abi3-macosx_11_0_arm64.whl (1.9 MB view details)

Uploaded CPython 3.10+macOS 11.0+ ARM64

File details

Details for the file mushroomdb-0.5.2-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for mushroomdb-0.5.2-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 a2ea48737287ebdf3cb32dfd6883b0cbdd081d1a481be81a8d3e2b6ec277cec1
MD5 5361037270eb4a3b485dd3e81dc51502
BLAKE2b-256 bf8daf57520bd89a150782deaa65233bb8f0f1809df4bed49d287523daf6a9ff

See more details on using hashes here.

Provenance

The following attestation bundles were made for mushroomdb-0.5.2-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: publish.yml on MatthewSherlin/mushroomdb

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file mushroomdb-0.5.2-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for mushroomdb-0.5.2-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 8ea97aaf5e8bc6a922dadc7c81c7fb800c2fe019d2cdeb6d567fc0678dd74f31
MD5 5d1f6b9c78e6dc0544848f49c95b7598
BLAKE2b-256 b5887449b117b61eeb124bedcd6c55b858453352c18a3c3c28fb99b419a498be

See more details on using hashes here.

Provenance

The following attestation bundles were made for mushroomdb-0.5.2-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl:

Publisher: publish.yml on MatthewSherlin/mushroomdb

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file mushroomdb-0.5.2-cp310-abi3-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for mushroomdb-0.5.2-cp310-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 1e5c48a5a52b9f7e9bd718c0bf108244897761aaadb82454a4a08b906310c87e
MD5 bece95a7eade559bf9121d7a54e1b79f
BLAKE2b-256 8e32073c933f41fded77452f3b436c169ae059934a5be790f08e282a9e6fb7b2

See more details on using hashes here.

Provenance

The following attestation bundles were made for mushroomdb-0.5.2-cp310-abi3-macosx_11_0_arm64.whl:

Publisher: publish.yml on MatthewSherlin/mushroomdb

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

0.5.2 This release

3 files

0.5.1

3 files

0.5.0

3 files

0.4.5

3 files

0.4.4

3 files

0.4.3

3 files

0.4.2

3 files

0.4.1

3 files

0.4.0

3 files

0.3.0

3 files

0.2.0

15 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page