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 (19 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] [--lock-wait-ms <ms>] <command> [args...]

--pretty and --lock-wait-ms are valid before or after the subcommand name; --db and --scope must come before it (or use the TOPODB_DB env var for the former).

Commands

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

Notes on individual commands:

• create-memory: stamped with a content_hash (stored as a node property for dedup tracking). If identical content (after whitespace normalization) was already stored, "deduplicated": true and the existing memory id is returned; --props is ignored on a hit. "deduplicated": false indicates a new memory. The response is {"id":…,"deduplicated":…}. --props is a JSON object string merged in alongside content; a --props that tries to set content itself is rejected (exit 2). The system-maintained keys content_hash and superseded_at are reserved — attempts to set them are rejected (exit 2).

• create-entity: now find-or-create by default — the name is matched case- and whitespace-insensitively across write scope and shared, and resolves aliases. An existing entity is returned with "created": false; --always-create restores the old raw-create behavior. Both paths now report the created flag. When created: false, --props merges only NEW keys; a name key in props is rejected either way (exit 2).

• remember: atomic store-and-link — one call creates a memory (with dedup), find-or-creates each named entity (same semantics as create-entity), and links them. Combines three operations into a single engine batch so facts never strand unlinked. --entity is repeatable (must pass ≥1). --supersedes is repeatable and marks the listed memory ids as superseded. --edge-type defaults to "about" and describes the link from memory→entity. The system-maintained keys content_hash and superseded_at are reserved — attempts to set them in --props are rejected (exit 2). Re-storing identical content from a superseded memory creates a new memory instead of deduping to the retired tombstone.

• forget: soft retirement — stamps forgotten_at (same tombstone mechanics as supersession) and closes the memory's open edges. Nothing is deleted: search --include-superseded and temporal reads still see the node. Every id must be a live Memory in the write scope; any invalid id rejects the whole call (exit 2). Re-remembering identical content later creates a fresh live memory — a tombstoned node is never a dedup target.

• link: --valid-from is Unix milliseconds; omit it to let the engine resolve "now".

• search: memories retired by remember --supersedes or forget (a superseded_at or forgotten_at timestamp in the past) are skipped by default — they neither surface, nor consume the --k window, nor get access-bumped. --include-superseded is the general history switch over the whole tombstone set — the same default-liveness shape get-edges has with --open-only. Matches the MCP server's search tool, which filters the same set.

• kind: an optional taxonomy on memories — episodic (dated observation), semantic (standing fact), procedural (how-to). An unstamped memory reads as semantic, so existing dbs need no migration. remember --kind stamps new memories (dedup ignores it — the stored kind wins); search --kinds filters by it. Kind never affects ranking.

• lifecycle-candidates: surfaces decay candidates — live memories ranked by kind-aware staleness ((age/half_life)/ln(e+access_count); half-life defaults 14d/120d/365d for episodic/semantic/procedural, absent kind counts as semantic). Deterministic under --now-ms, read-only, and unbumped (the sweep never perturbs the access signal it reads). It only PROPOSES: review the evidence and retire memories explicitly with forget.

• purge: DESTRUCTIVE. Hard-deletes every memory whose superseded_at/forgotten_at tombstone is strictly older than --tombstoned-before (unix-ms). Dry-run by default — nothing is written until --yes. Purged history is gone: --include-superseded and as_of queries stop seeing those nodes; that is the point. Deliberately CLI-only (no MCP surface) and never part of the /sgh:lifecycle graph — reclamation is an operator action, not an agent one.

• 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. --as-of <unix-ms> performs a temporal read at the given Unix millisecond timestamp (closed edges reappear, later edges vanish); a future as_of behaves like "now". Omit to read "now".

  Example: topodb --db agent.redb traverse <id> --as-of 1700000000000 reads the graph as it was at the given instant, showing edges that were open then (including edges since closed) and hiding edges created after.

• get-edges: list a node's outgoing edges, optionally filtered by target node (--to) and/or edge type (--edge-type). --open-only true (default) shows only open edges; --open-only false shows the full history (open + closed). --as-of <unix-ms> performs a temporal read within the window valid_from <= t < valid_to (valid_to exclusive; a future as_of behaves like "now"), and is mutually exclusive with --open-only (since as_of already means "edges open at that instant"). Use this to find the edge id to pass to close-edge when a fact stops being true, or to check what a node is already linked to.

  Example — list all edges ever created from an entity, including closed ones:

  $ topodb --db agent.redb get-edges <entity-id> --open-only false
  

• 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.

• submit [input]: submit a JSON array of batch commands atomically. Each command has an op field (the command type) and type-specific fields. #N in an id field is 0-indexed: #0 refers to the first command's produced id, #1 to the second command's produced id, etc. Reads from input file path, or stdin if - or omitted. This matches submit_batch in topodb-mcp.

Exit-code contract

On failure, stderr carries {"error": {"kind": "busy"|"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":6,"index_spec":{"equality":[{"label":"Entity","prop":"name"},{"label":"Alias","prop":"name"},{"label":"Synonym","prop":"term"},{"label":"Memory","prop":"content_hash"}],"text":[{"label":"Memory","prop":"content"},{"label":"Entity","prop":"name"},{"label":"Alias","prop":"name"}]},"path":"demo.redb"}

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

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

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

$ topodb --db demo.redb search "first program"
[{"node":{"id":"01KY6TA0DC8YYBKMW9XJASEQ07","label":"Memory","props":{"content":"ada wrote the first program","content_hash":"ba78ad81d00f6917"},"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