hivemind-json-db-plugin

JSON-file database backend for hivemind-core. It implements the hivemind-plugin-manager AbstractDB contract on top of json_database's JsonStorageXDG.

This is the simplest of the three first-party HiveMind database backends. It stores data as a single plain JSON file on disk, needs no daemon, and supports optional AES-GCM encryption. It suits small single-node deployments, dev environments, and CI.

---

Where to look

You want to...	Read
Install and run for the first time	Getting Started
Configure paths, encryption, server.json	Configuration
Understand the on-disk layout and design trade-offs	Architecture
Look up JsonDB methods	API Reference
Read schema migration semantics	Migration
Back up, restore, edit by hand, recover	Operations
Diagnose an error or oddity	Troubleshooting
Decide between JsonDB / SQLite / Redis	Comparison
Contribute code or open a PR	Contributing

---

When to pick this plugin

Pick JsonDB when:

• You have a single HiveMind node and a few dozen to a few thousand clients.
• You want the database to be a text file you can cat, grep, edit, and commit to git.
• Your client list changes infrequently. Every write rewrites the whole file.
• You want zero external dependencies (no SQLite library, no Redis server).

Pick something else when:

• You have tens of thousands of clients or heavy write churn. Use hivemind-sqlite-database for an indexed, in-place-updated store.
• You need to share a client DB between multiple HiveMind processes or nodes. Use hivemind-redis-database.
• You need encryption with key rotation, audit logs, or HSM-backed keys. The optional password=... here is AES-GCM symmetric. It protects data at rest but does not cover key-management workflows.

See Comparison for the full matrix.

---

A 60-second tour

from hivemind_plugin_manager import DatabaseFactory

db = DatabaseFactory.create("hivemind-json-db-plugin")
# -> <JsonDB ... path=~/.local/share/hivemind-core/clients.json>

db.add_item(Client(client_id=1, api_key="abc", name="kitchen-pi",
                   allowed_types=["recognizer_loop:utterance"]))
db.commit()

for client in db:
    print(client.client_id, client.name)

The plugin is registered under the hivemind.database entry-point group as hivemind-json-db-plugin. Any hivemind-plugin-manager-aware consumer discovers it automatically.