Solo and offline use
The Rust CLI can keep a graph in .deciduous/deciduous.db without a running server. Use this for an independent offline project or a local copy you want to inspect. For agents that must read one another's current decisions, use shared Postgres and HTTP MCP instead.
Start a local graph
Install the current CLI and initialize the repository:
brew tap notactuallytreyanastasio/tap
brew install deciduous
deciduous init
deciduous add goal "Make retries bounded" -p "Make retries stop after a bounded delay."
deciduous nodes
deciduous serve
init creates local state and agent integration files. Review generated instructions before using them; a local CLI workflow and a shared-server workflow have different write destinations. Keep the SQLite database out of Git.
Use deciduous add --help, link --help, and other command help from your installed version for details. Local node references can use an integer ID or a supported change_id prefix. Server MCP tools generally require the server's full UUID instead.
Feature boundaries
| Capability | Shared HTTP MCP / Postgres | Local Rust CLI / stdio MCP |
|---|---|---|
| Read and write decisions | Shared tools such as add_node, query_nodes, add_edge |
Local commands and a separate stdio tool set |
| Workspace-wide cross-branch reads | Yes, without copying between agent machines | Reads the local database's current contents |
| Activity and branch leases | check_activity, short MCP write leases |
No equivalent shared-service coordination |
| Live writes | /events and remote watch |
Local viewer reads local data; not the remote event stream |
| Borrowing provenance | took_from edges; log_observation helper |
deciduous link ... -t took_from in the local graph |
| Documents | Stored metadata and uploaded bytes; HTTP import/upload/read endpoints | doc commands and stdio attachment tools |
| Themes and assignments | Schema/export support, but no registered theme-editing MCP tools | Theme/tag commands and stdio tools |
| DOT images and PR writeups | No registered export-DOT or writeup tools | dot, writeup, and corresponding stdio tools |
| Explicit local conversation sessions | Not the HTTP MCP session model | Local stdio session tools and .deciduous/active_session |
| Offline edits | No automatic queue for the shared server | Available locally; later transfer needs review |
| Git graph synchronization | Not the Postgres write path | .deciduous/graph.json and deciduous sync |
The shared server and local stdio MCP do not promise feature parity. Discover the tools on the connection you are using. An imported field appearing in a graph snapshot does not imply that a dedicated shared tool can edit it.
Inspect a local copy of the shared graph
After configuring the CLI remote, you can pull nodes and edges and open the local viewer:
deciduous remote status
deciduous remote pull
deciduous serve
This is a partial local copy. Pull does not download attachment bytes or reproduce all server deletions, and it does not keep running in the background. The local viewer is therefore not proof of the server's current state. Query the HTTP tools for an authoritative team read.
Treat the copy as inspection data. A local add, link, or status update still writes to SQLite. Do not bulk-push those local changes into a busy workspace to make them visible; the import path can replace newer server fields. Record new shared work through HTTP MCP.
Optional Git-based collaboration
For a team that chooses the local/Git model instead of a shared service, .deciduous/graph.json holds the records exchanged through Git. Local mutations write the record store, and deciduous sync reconciles it with SQLite.
git pull
deciduous sync
deciduous sync --check
git status --short
Review the graph file before staging it by name. It can contain user prompts, paths, descriptions, and metadata. Keep private records out of a public repository. sync --check uses a nonzero exit status to report pending reconciliation; read its output before treating that as a command failure.
Local numeric IDs differ between machines. Use change IDs for durable references. The merge driver and reconciliation use record timestamps, so inspect conflicts involving concurrent edits to the same reasoning. Document bytes and local session/command records are not a complete part of this Git exchange.
Git-based synchronization does not contact the shared Postgres server. Avoid running the two collaboration models as if they were one automatic replication system.
Move to the shared service
Keep a backup of the local database and document files, choose a workspace name the whole team will use, and follow upgrading and migration. The supplied procedure checks the target and handles content uploads separately from graph metadata.
After migration, connect agents to the shared HTTP MCP endpoint and replace local-write instructions in their project guidance. Retain the old database as a migration backup. Do not delete it merely because the new workspace has matching node counts.