Skip to content

cli.md

Latest commit

 

History

History
323 lines (227 loc) · 10.6 KB

cli.md

File metadata and controls

323 lines (227 loc) · 10.6 KB
Raw

documentdb-memory CLI reference

The documentdb-memory binary is the operator-facing surface of this project. It is not required at runtime by the MCP server (the server is the documentdb-memory-mcp bin) — the CLI exists to bootstrap, inspect, repair, and back up the two MongoDB-protocol databases the server reads from and the sync daemon writes to.

This page is the authoritative reference for command grammar. Every option listed here was checked against src/cli/commands/ in this repository; if a flag appears in --help but is not here, that is a bug — please file an issue.

Conventions

  • <angle> — required positional argument.
  • [square] — optional argument or flag.
  • All commands resolve config in the same order: CLI flag → env var → default. The relevant env vars are listed in .env.example.
  • On error, the CLI prints a single red line. Pass --debug (where supported) or set DEBUG=1 for a full stack trace.
  • Commands that take a duration accept the grammar <number><unit>, where unit is one of ms, s, m, h, d, w. Decimals are allowed (1.5h). Bare integers (no unit) are rejected.
  • Commands that take a cutoff (--older-than) accept either a duration (interpreted as "now minus this") or an ISO-8601 date/time (2024-01-15T00:00:00Z).

Global / shared options

These apply to most top-level commands. They do not bubble up from subcommands — pass them on the immediate command that documents them.

Flag Default Notes
--uri <uri> $DOCUMENTDB_URI MongoDB-protocol connection string.
--db <name> $DOCUMENTDB_DB or copilot_memory Target database.
--debug off Print full error stack traces. Available on graph and sessions parents.
--json off Where supported, emit machine-readable JSON instead of human text.

documentdb-memory doctor

Connectivity and configuration self-check. Run this first if anything seems off.

documentdb-memory doctor [--uri <uri>] [--db <name>] [--source <path>] [--json]

Options:

  • --source <path> — path to the Copilot CLI session-store SQLite file used by sessions sync. Defaults to $COPILOT_SESSION_STORE or $HOME/.copilot/session-store.db.
  • --json — emit one JSON object per check.

Checks performed (in order, fail-fast):

  1. config-resolve — env / flags parse cleanly.
  2. mongo-connect — MongoClient.connect() succeeds.
  3. mongo-db-readable — db.command({ping:1}) succeeds.
  4. graph-indexes — graph_entities and graph_relations indexes are present (creates them if not — ensureGraphIndexes is idempotent).
  5. history-indexes — same, for the history_* collections.
  6. session-store-path — the SQLite file is present and readable.
  7. fuse-mount — only run if the FUSE_MOUNT_PATH env var is set (manually; this knob is intentionally not in .env.example). Stats ${FUSE_MOUNT_PATH}/${DOCUMENTDB_DB} to confirm the mirror is visible.

Exit code is 0 if every check passes, 1 otherwise.

documentdb-memory graph

The knowledge-graph track. Read/write graph_entities and graph_relations. The MCP server reads from the same collections, so anything you write here is immediately visible to a Copilot session using the documentdb-memory-mcp server.

Parent options: --uri, --db, --debug.

graph add entity <name>

Insert one entity. Idempotent — re-adding the same name is a no-op (duplicate-key errors are swallowed; observations are appended).

documentdb-memory graph add entity <name> --type <T> [--obs <text>...]
  • --type <T> — required. Entity type (e.g. Person, Project).
  • --obs <text> — optional, repeatable. Each occurrence is appended as a separate observation.

graph add relation <from> <to> <type>

Insert one relation. _id is computed as ${from}__${type}__${to} (double underscore) so the same triple cannot be inserted twice.

documentdb-memory graph add relation <from> <to> <type>

graph add obs <entity> <text>

Append one observation to an existing entity. Errors if the entity does not exist.

documentdb-memory graph add obs <entity> <text>

graph delete entity <name>

Remove an entity and cascade-delete any relation referencing it as from or to.

documentdb-memory graph delete entity <name>

graph delete relation <from> <to> <type>

Remove exactly one relation triple.

graph delete obs <entity> <text>

Remove a single observation by exact-string match.

graph prune

Time-based cleanup. Removes entities not updated since <when>; cascades to their relations.

documentdb-memory graph prune --older-than <when> [--dry-run] [--json]
  • --older-than <when> — required. Duration (30d, 4w) or ISO-8601.
  • --dry-run — print what would be deleted; touch nothing.
  • --json — machine-readable summary.

graph wipe

Drop both graph collections and re-run the index bootstrap. Asks for confirmation unless --yes is passed.

documentdb-memory graph wipe [--yes]

graph stats

Counts and small summary (top entity types, oldest/newest updated_at).

documentdb-memory graph stats [--json]

graph dump

Full JSON snapshot to stdout. The --json flag is required (it is currently the only output mode).

documentdb-memory graph dump --json

graph export <file>

Stream the entire graph to a single newline-delimited JSON (.jsonl) file. Each line is one of:

{"type": "entity",   "name": "...", "entityType": "...", "observations": [...]}
{"type": "relation", "from": "...", "to": "...", "relationType": "..."}

This format is byte-compatible with the official @modelcontextprotocol/server-memory dump format — you can hand the file to that server's --memory-file-path flag.

graph import <file>

Inverse of export. Reads a .jsonl file in the same format.

documentdb-memory graph import <file> [--merge | --replace]
  • --merge (default) — insert-or-update; existing entities get new observations appended.
  • --replace — wipe the graph first, then import. Use with care.

graph reembed

Recompute DocumentDB Search embeddings for existing entities. Useful after enabling the feature for the first time, or after switching embedding models (existing vectors from a different model are stale).

documentdb-memory graph reembed [--all]
  • default — embed only entities whose vector is missing or was produced by a different model.
  • --all — force re-embed every entity.

Requires an embedding provider to be configured and reachable (MEMORY_EMBEDDING_PROVIDER, default local). If none is available the command warns and makes no changes. See the DocumentDB Search section of the README.

documentdb-memory sessions

The session-history track. Manages the DocumentDB mirror of Copilot CLI's local session-store.db. The CLI never modifies the local SQLite file; every operation here only touches MongoDB-protocol collections.

Parent options: --uri, --db, --debug.

sessions sync

Mirror the local SQLite into DocumentDB. This is the workhorse command.

documentdb-memory sessions sync [--once | --watch | --full]
                                [--interval <dur>]
                                [--source <path>]
                                [--json]

Modes (mutually exclusive; --once is the default if none is given):

  • --once — incremental pass using each table's watermark; exit 0.
  • --watch — incremental pass every --interval, forever. Pino logs to stderr; progress lines to stdout.
  • --full — ignore watermarks; re-upsert every row in the source. Useful after a sessions wipe or to repair drift.

Other flags:

  • --interval <dur> — only with --watch. Defaults to $SYNC_INTERVAL (30s).
  • --source <path> — override the SQLite path.
  • --json — machine-readable summary. Rejected with --watch (no terminator).

sessions purge

Delete old sessions and everything they own. Cascades through history_turns, history_checkpoints, history_session_files, history_session_refs, and history_search_index. Does not touch history_dynamic_context_items (globally scoped) or history_sync_state (sync metadata).

documentdb-memory sessions purge --older-than <when> [--dry-run] [--json]

sessions wipe

Drop every history_* collection, including history_sync_state. The next sync run will therefore re-mirror every row from SQLite (effectively a --full).

documentdb-memory sessions wipe [--yes]

sessions export <dir>

Write one <collection>.jsonl file per history_* collection into <dir>. The directory is created if missing.

documentdb-memory sessions export <dir>

sessions import <dir>

Inverse of export. Reads every <collection>.jsonl in the directory.

documentdb-memory sessions import <dir> [--merge | --replace]

sessions dump --collection <name>

Dump one collection to stdout.

documentdb-memory sessions dump --collection <name> --json [--jsonl]
  • --collection <name> — required. One of the history_* collections.
  • --json — currently the only output mode; explicit flag required.
  • --jsonl — emit one object per line (streaming) instead of a single JSON array.

Deployment templates

If you want to run the sync daemon as a host service instead of inside docker compose, the repo ships init-system templates at:

  • deploy/launchd/com.documentdb.copilot-memory-sync.plist — macOS user-level LaunchAgent.
  • deploy/systemd/documentdb-copilot-memory-sync.service — Linux user-level systemd unit.

Both templates wrap documentdb-memory sessions sync --watch --interval 30s and require you to edit the binary path and DOCUMENTDB_URI before loading. The full lifecycle (load, reload, unload, log paths, troubleshooting) lives in deploy/README.md.

The container-based alternative — docker compose -f compose.full.yml up -d — is documented in architecture.md.