Quick Start

Developer reference for what Trove implements today. First time here? Follow Try in a day for a guided afternoon experiment instead.

What works today

Build and run the CLI:

git clone https://github.com/joshmcarthur/trove.git
cd trove
make build
./bin/trove -version

The config loader (internal/config), SQLite journal (internal/journal), blob store (internal/blob), module runtime (internal/modules), HTTP gateway (internal/gateway), HTTP ingest module (modules/http-ingest), MQTT source (modules/mqtt-source), Telegram source (modules/telegram-source), deferred capture (modules/capture-classifier), and MCP query (internal/query + modules/mcp-query) are implemented. With a valid config file, trove opens the journal, discovers modules, supervises them, and starts the HTTP gateway (ingest, blobs, capture, classify, MCP) until interrupted:

make build
trove init
trove -config ./trove.toml

Or pass an existing config path:

make build
trove -config /path/to/trove.toml

Point [modules].paths at the parent directory containing module installs (for example, the repo modules/ directory after make build). Then POST JSON to POST /ingest/:source on the HTTP gateway listen address (default :8080).

Example config

[journal]
path = "./trove.db"

[modules]
paths = ["./modules"]

[http]
listen = ":8080"

Query the journal

Connect Cursor (or another MCP client) to http://<host>:8080/mcp on the HTTP gateway — see MCP client setup. Three core record tools are always available: search_records, get_record, and list_incomplete_records. Additional tools appear when modules that register MCP tools are loaded.

MQTT source subscribes to configured topics in modules/mqtt-source/manifest.toml (default broker tcp://localhost:1883, topics ["home/#"]). See MQTT source planning and building modules.

What's coming

  • Two-week live test — capture recipes and conversational retrieval validation (see roadmap)

Photo attachments work today via PUT /blobs then ingest with blob_ref — see iOS Shortcuts.

Capture records

  1. Configure paths in TOML (see configuration).
  2. Start trove — core loads modules from configured paths.
  3. POST JSON to POST /records to append a revision and materialize a record.

HTTP ingest responses

Status Meaning
201 Record accepted (body includes revision_id, record_ref, version)
400 Invalid JSON, missing body, or bad type / time / blob_ref
405 Non-POST request to /records
500 Internal append failure

iOS Shortcuts

Import a ready-made Shortcut or build your own — see iOS Shortcuts. All Shortcuts POST JSON to https://<your-host>/ingest/shortcuts; the :source path segment becomes the event source field.

Next steps