cli.md

CLI reference

Six subcommands, one shared flag (--db). Skip --db on a directory and remindb derives ./<dirname>.db for you.

← back to README · related: configuration · architecture

remindb compile <path>   Ingest files or a directory into the database
remindb serve            Start the MCP server (stdio or HTTP)
remindb inspect          Dump DB stats; optionally render the node tree or file list
remindb bench            Measure token savings vs. raw-file baselines
remindb doctor           Run integrity checks; --fix self-heals
remindb update           Reinstall remindb by re-running the install script

Everything that lives under .remindb/ — runtime config, ignore patterns, temperature pre-seeding — has its own page: configuration. This page is the subcommands.

compile

One-shot ingestion of a file or directory. Creates a new snapshot and records diffs against the previous one. Files with an unsupported extension or unparseable content (e.g. a .json carrying comments or trailing commas, as tsconfig.json often does) are skipped with a warning rather than aborting the whole compile.

remindb compile ./notes # → ./notes.db
remindb compile ./notes --db memory.db -m "add Q2 notes"
remindb compile ./docs/architecture.md --db project.db
remindb compile ./notes --reseed-temperatures # force .remindb/temperatures.json values onto unchanged nodes

Flag	Purpose
--db PATH	Target database. Default: derived from the source directory name, else memory.db.
-m, --message	Snapshot message (defaults to compile:<path>).
--reseed-temperatures	Push .remindb/temperatures.json values through to nodes whose source files didn't change on disk. Directory compiles only; no new snapshot. See configuration → pre-seeding temperatures.
--reseed-pinned	Re-apply pin status from .remindb/pinned to every node from a matching file, overriding prior MemoryUnpin choices. Directory compiles only; no new snapshot. Combine with --reseed-temperatures for an atomic-per-node pin + temperature reseed. See configuration → pre-seeding pins.

serve

Starts the MCP server. Default transport is stdio (one server per client process); pass --transport http to expose the same Memory* suite over streamable HTTP so a CI worker or a hosted agent session can connect to the same memory database. With --source set, remindb runs an initial compile (if the DB is empty) and keeps a background rescan loop running. Omit --source (and REMINDB_SOURCE) to run in DB-only mode — the server opens an existing DB and exposes the MCP surface without filesystem watching.

remindb serve --db ./notes.db --source ./notes
remindb serve --db ./notes.db --source ./notes --rescan-interval 30s -v
remindb serve --db ./notes.db --source ./notes --transport http
remindb serve --db ./notes.db --source ./notes --transport http --listen 127.0.0.1:7474
remindb serve --db ./notes.db # DB-only (no source, no rescan)

HTTP defaults to 127.0.0.1:7474. Binding to a non-loopback address (e.g. --listen 0.0.0.0:7474) requires authentication — serve refuses to start unless REMINDB_AUTH_TOKEN is set (every request must then carry Authorization: Bearer <token>; constant-time-rejected 401 + WWW-Authenticate: Bearer realm="remindb" otherwise) or --insecure-public is passed (deliberately ugly opt-out for homelab / reverse-proxy setups where you trust the network layer; logs a startup Warn). Loopback binds need no auth, but setting REMINDB_AUTH_TOKEN still applies the middleware. See SECURITY.md for the full transport threat model.

Flag	Env	Purpose
--db	REMINDB_DB	Database file.
--source	REMINDB_SOURCE	Source directory to watch and incrementally recompile. Omit for DB-only mode.
--rescan-interval	REMINDB_RESCAN_INTERVAL	e.g. 30s, 5m. 0 keeps the tracker's default. Requires --source.
--transport	REMINDB_TRANSPORT	stdio (default) or http. Also server.transport — see configuration → precedence.
--listen	REMINDB_LISTEN	Listen address for HTTP transport. Default 127.0.0.1:7474; requires --transport=http. Also server.listen.
--insecure-public	REMINDB_INSECURE_PUBLIC	Bypass HTTP auth requirement when binding non-loopback (DANGEROUS, env-acceptable values per strconv.ParseBool). Requires --transport=http.
—	REMINDB_AUTH_TOKEN	Shared bearer token enforced on every HTTP request when set. Env-only — no flag mirror, no config-file slot, to keep secrets out of committed configs.
-v, --verbose	—	Force debug-level logs (default info). Sugar for server.logging.level=debug; wins over config.

serve background-checks GitHub releases on startup and emits an info log when a newer tag is available, with hint=remindb update — the prompt to upgrade comes from the server, the upgrade itself is one command.

inspect

Read-only snapshot of what's in a database. Without --tree or --files it prints stats; --tree renders the node hierarchy (temperatures colour-coded blue cold → red hot); --files renders the compiled source files grouped by compile root.

remindb inspect --db ./notes.db
remindb inspect --db ./notes.db --tree --depth 6
remindb inspect --db ./notes.db --files

Flag	Purpose
--tree	Render the node tree.
--files	Render compiled source files grouped by compile root.
--depth N	Maximum depth when rendering. Default: 10. Requires --tree.

NO_COLOR=1 disables the ANSI palette. (MemoryStats returns the same stats over MCP as exact integers; the CLI abbreviates large token counts for readability.)

bench

Runs the scenario suite — tree · search · fetch · delta — against one database and prints token savings compared to a naive list + read + grep baseline.

remindb bench \
  --db ./notes.db --dir ./notes --budget 1000 \
  --query "WebSocket idempotency" --query "Snowflake COPY INTO"

Flag	Purpose
--dir	Source directory (inferred from the DB path if omitted).
--budget	Token budget for search and fetch scenarios. Default: 1000.
--query	Repeatable. Skips the search scenario when empty.

doctor

Runs integrity checks against the database — the kind of structural invariants a corrupted compile or an interrupted write could break. By default it only reports. Pass --fix and it attempts to repair the failed checks, taking a timestamped backup first so a botched repair is never destructive.

remindb doctor --db ./notes.db          # report only
remindb doctor --db ./notes.db --fix    # self-heal (backs up first)
remindb doctor --db ./notes.db --json   # machine-readable, for CI

Flag	Purpose
--fix	Attempt to repair failed checks. Takes a timestamped backup before touching anything.
--json	Emit machine-readable JSON instead of the human report.

Reach for doctor when search results look wrong, a compile died mid-run, or you want a CI gate that a synced .db is structurally sound before it ships.

update

Reinstalls remindb in place by re-running the official install script — install.sh piped to bash on Linux / macOS, install.ps1 piped to PowerShell on Windows. It reads the installed version, compares against the latest GitHub release, and only re-runs when they differ. dev-builds (from go build / go install) always proceed; there's no published version to compare against.

remindb update
remindb update --force   # reinstall regardless of version