topodb-cli

A direct-embedded, script-friendly command-line interface over a TopoDB agent-memory database file. JSON in, JSON out, predictable exit codes — no server process, no network hop.

Status: v1 — the full read/write surface (17 commands). See v1 limitations.

Install

cargo install topodb-cli

This installs a binary named topodb (not topodb-cli) to your Cargo bin directory (typically ~/.cargo/bin), which must be on PATH.

Global flags

topodb --db <path> [--scope <ulid|shared>] [--pretty] <command> [args...]

Commands

All 17 subcommands, in scaffold + write + read order:

Notes on individual commands:

• create-memory/create-entity: --props is a JSON object string merged in alongside the reserved key (content / name); a --props that tries to set the reserved key itself is rejected (exit 2), it never silently overwrites.
• link: --valid-from is Unix milliseconds; omit it to let the engine resolve "now".
• find: --value is parsed as a JSON scalar first (42 → Int, true → Bool, "ada" → Str); if it doesn't parse as JSON at all, the raw string is taken as Str — so --value ada and --value '"ada"' are equivalent. A float value is never equality-indexable and comes back rejected. find errors (exit 2) if (label, prop) isn't declared in the open db's index spec.
• traverse: omitting --edge-type entirely follows every edge type; passing it (once or repeated) restricts the walk to exactly those types.
• changes: the one unscoped command — see Scoping — and Compacted (the requested --since is below the retained floor) is a rejected/exit-2 condition, not an internal error; the caller re-anchors from info's current_seq rather than trusting a truncated tail.
• compact: drops every op-log entry with seq < --keep-from.

Exit-code contract

On failure, stderr carries {"error": {"kind": "rejected"|"internal", "message": "..."}}; stdout is left empty. clap's own usage errors print clap's own message (not this JSON shape) but still exit 2.

Scoping

A write is stamped with exactly one scope; a read filters by a set. That asymmetry is the model, not an oversight.

• The global --scope (default shared) supplies the default for every command except changes.
• Per-command --scope override. The three commands that stamp a scope — create-memory, create-entity, link — each take their own --scope <ulid|shared>, overriding the global one for that invocation. This matches submit's batch DSL (whose create_memory, create_entity, and link ops each take an optional scope field) and the topodb-mcp tools of the same names.
• set-props, remove-node, close-edge, and set-embedding address an existing node or edge by id and stamp no scope of their own, so they take no --scope.
• link --scope is what keeps shared memories connected. An edge created while --scope names a project is stamped with that project, so it is invisible from every other project — the nodes would be shared but disconnected. Pass --scope shared on a link between shared nodes.
• changes is deliberately unscoped: the op log spans every scope, so a host can replay it for cross-scope consolidation. There's no way to filter it by scope on this CLI.

Why changes isn't gated here, but get_changes is on topodb-mcp

topodb-mcp serves get_changes only when started with --allow-unscoped-changes. This CLI needs no such flag. The difference is deliberate.

The MCP gate prevents accidents, not attackers. MCP advertises get_changes in the model's tool list, so an agent can trip over it while doing something else and replay every other project's writes into its own context. This CLI advertises nothing to a model: reaching changes takes deliberate intent, and whoever can run topodb --db <file> changes already holds the file and could read it directly.

Accepted risk, stated plainly: an agent with shell access bypasses the MCP gate entirely by invoking this CLI against the same database file. --allow-unscoped-changes is not a security boundary and nothing here pretends otherwise. If a future host drives this CLI from an agent loop, that decision needs revisiting.

v1 limitations

• No --spec flag. An existing db is always opened with its own persisted index spec; a fresh one is created with the canonical default (equality on Entity/name, text on Memory/content). There's no way to declare a different spec from this CLI.
• No multi-scope reads. Every read filters by the single scope named in the global --scope. topodb-mcp can read across a set of scopes (--read-scopes, and a scopes param on its read tools); this CLI cannot. To read another scope, run again with a different --scope.
• Direct-embedded only, single-process access. There's no --connect/HTTP mode — the CLI opens the .redb file directly in-process, the same way topodb-mcp does. You can't run topodb against a database file another process (another topodb invocation, or a running topodb-mcp server) currently has open; opening fails as a db-open error (exit 1). Point the CLI at the file only when nothing else has it open, or use a separate file per concurrent consumer.

The removed bullets ("No vector search", "No set-props/remove-node", "No bulk/stdin submit") were all false. search-vector, set-props, remove-node, and submit exist.

Examples

Fresh database, info:

$ topodb --db demo.redb info
{"current_seq":0,"default_scope":"shared","format_version":1,"index_spec":{"equality":[{"label":"Entity","prop":"name"}],"text":[{"label":"Memory","prop":"content"}]},"path":"demo.redb"}

Create an entity and a memory, then search for it:

$ topodb --db demo.redb create-entity --name ada
{"id":"01KX2NZY1CCS7GVF59C8H909GG"}

$ topodb --db demo.redb create-memory --content "ada wrote the first program"
{"id":"01KX2NZY4VH5QQC16VHXHJSKFE"}

$ topodb --db demo.redb search "first program"
[{"node":{"id":"01KX2NZY4VH5QQC16VHXHJSKFE","label":"Memory","props":{"content":"ada wrote the first program"},"scope":"shared"},"score":0.5753642320632935}]

get on an id that doesn't exist — still exit 0:

$ topodb --db demo.redb get 01ARZ3NDEKTSV4RRFFQ69G5FAV
{"found":false}
$ echo $?
0