CLI reference

quaid is a single binary that exposes the entire memory over a Unix-style CLI. This page documents every subcommand grouped by domain. For the authoritative flag list on your installed version, run quaid --help or quaid <command> --help.

Global options

These flags apply to every subcommand and may appear before or after the command name.

Flag	Description
--db <PATH>	Database path. Env: QUAID_DB. Default: ./memory.db.
--model <ALIAS|HF_ID>	Embedding model. Env: QUAID_MODEL. Default: small. Recognized aliases: small, base, large, m3. Any other value is treated as a Hugging Face model ID (online build only).
--json	Emit JSON instead of human-readable text. Most commands honor this.
--help, -h	Print help. Works at root or per-command.
--version, -V	Print version and exit.

Data — read and write

init [PATH]

Create a new memory database. Records the active embedding model in quaid_config so subsequent opens validate against it.

quaid init ~/memory.db
quaid init ~/memory-large.db --model large   # online build only

get <SLUG>

Read a page by slug. Slugs may be collection-qualified (<collection>::<slug>) when more than one collection is attached.

quaid get people/alice
quaid get research::people/alice

put <SLUG>

Write or update a page from stdin. For updates, supply --expected-version to enable optimistic concurrency (OCC). On a conflict the call fails and you must re-fetch before retrying.

cat updated.md | quaid put people/alice --expected-version 7

Flag	Type	Default	Notes
--expected-version <N>	i64	none	Required for safe updates; absent means “create only”.

list

List pages with optional filters.

Flag	Type	Default
--wing <NAME>	string	none
--type <TYPE>	string	none
--limit <N>	u32	50

search <QUERY>

FTS5 full-text search. By default the input is sanitized so natural-language queries with ?, !, etc. work without escaping. Pass --raw to send the query verbatim and use FTS5 expert syntax (quoted phrases, boolean operators, prefix wildcards).

Flag	Type	Default
--wing <NAME>	string	none
--limit <N>	u32	10
--raw	flag	false

quaid search "river ai"
quaid search '"local-first" AND (sqlite OR fts5)' --raw

query <QUERY>

Hybrid retrieval: FTS5 + vector similarity, fused via set-union. Use --depth auto to enable progressive expansion — the engine grows the context window until the token budget is exhausted.

Flag	Type	Default
--depth <auto|''>	string	auto
--limit <N>	u32	10
--token-budget <N>	u32	4000
--wing <NAME>	string	none

quaid query "who is interested in offline-first knowledge systems?"

Ingest — files, export, embed

ingest <PATH>

Single-file ingestion with SHA-256 idempotency. Re-running on the same file is a no-op unless --force is set.

Flag	Type	Default
--force	flag	false

There is no import command. To bring in a markdown directory, attach it as a collection (quaid collection add <name> <path>, then quaid collection sync <name>); page types are inferred from a PARA-style folder layout (project(s)/, area(s)/, resource(s)/, archive(s)/) after stripping numeric prefixes such as 1-projects/.

export <PATH>

Export every page to a markdown directory.

Flag	Type	Default
--raw	flag	false
--import-id <ID>	string	none

--raw writes byte-for-byte the original ingested content (preserves frontmatter ordering and whitespace); without it, the export is the canonicalized form.

embed [SLUG]

Generate or refresh embeddings.

Flag	Type	Default
--all	flag	false
--stale	flag	false
--batch-size <N>	usize	32

quaid embed people/alice          # one page
quaid embed --stale                # only re-embed pages whose chunks changed
quaid embed --all                  # scan every page; skip current chunks
quaid embed --all --batch-size 16  # scan pages in smaller batches

Conversation extraction and models

extraction <enable|disable|status>

Manage SLM-based conversation extraction.

quaid extraction enable    # enable extraction and eagerly cache the configured model
quaid extraction disable   # disable extraction; cached model files are kept
quaid extraction status    # show extraction configuration and cache state

extract [SESSION_ID]

Re-enqueue manual extraction for one or more conversation sessions.

Flag	Type	Notes
--all	flag	Re-extract every known session; conflicts with SESSION_ID
--since <DATE>	YYYY-MM-DD	Restrict --all to day-files dated on or after the date
--force	flag	Reset conversation cursors to turn 0 first; requires SESSION_ID

model <pull|status|clean>

Manage cached local models.

quaid model pull <alias>            # download an extraction SLM into the model cache
quaid model status [alias]          # cache status; --verbose, --verify
quaid model clean [alias]           # remove stale/invalid entries; --list, --all, --force

Graph — links and backlinks

link <FROM> <TO>

Create a typed temporal cross-reference. Both ends must exist as pages.

Flag	Type	Default
--relationship <NAME>	string	related
--valid-from <DATE>	ISO-8601	none (open-start)
--valid-until <DATE>	ISO-8601	none (open-end)

link-close <LINK_ID>

Close an open temporal link interval by setting valid_until.

Flag	Type
--valid-until <DATE> (required)	ISO-8601

links <SLUG>

List outbound links from a page, with link IDs.

Flag	Type	Default
--temporal <current|all>	string	current

unlink <FROM> <TO>

Remove a cross-reference entirely. With --relationship, only that edge is removed.

Flag	Type	Default
--relationship <NAME>	string	none (remove all)

backlinks <SLUG>

List inbound links to a page.

Flag	Type	Default
--temporal <current|all>	string	current

graph <SLUG>

N-hop neighbourhood graph from a page (BFS over links, with temporal filtering).

Flag	Type	Default
--depth <N>	u32	2
--temporal <current|all>	string	current

Tags and timeline

tags <SLUG>

Manage tags. Both --add and --remove are repeatable.

quaid tags people/alice                       # list
quaid tags people/alice --add infra --add ops # add two tags
quaid tags people/alice --remove ops          # remove one

timeline <SLUG>

Show timeline entries for a page.

Flag	Type	Default
--limit <N>	u32	20

timeline-add <SLUG>

Append a structured timeline entry. --date and --summary are required.

Flag	Type	Required
--date <DATE>	ISO-8601	yes
--summary <TEXT>	string	yes
--source <REF>	string	no
--detail <TEXT>	string	no

Intelligence — checks and gaps

check [SLUG]

Run contradiction detection on a single page or, with --all, every page. Heuristic; backed by the assertions table.

Flag	Type
--all	flag
--type <TYPE>	string

gaps

List unresolved knowledge gaps. By default only unresolved gaps are returned.

Flag	Type	Default
--limit <N>	u32	20
--resolved	flag	false

Maintenance

validate

Memory integrity checks. With no flags, all checks run.

Flag	Type
--all	flag
--links	flag
--assertions	flag
--embeddings	flag

compact

Checkpoint the SQLite WAL into a single file. Safe to run while no writers are active.

stats

Memory statistics: page count, link count, gap count, active embedding model.

quaid stats
quaid stats --json

Collections — vault sync (Unix, v0.9.6)

collection groups all vault-sync subcommands. See Manage collections for end-to-end guidance.

quaid collection add notes ~/Documents/Obsidian --writable
quaid collection list
quaid collection info notes
quaid collection sync notes
quaid collection ignore add notes "_attachments/**"
quaid collection quarantine list notes

Subcommands: add · list · info · sync · restore · restore-reset · reconcile-reset · ignore add|remove|list|clear · quarantine list|export|discard|restore.

Namespaces

namespace <create|list|destroy>

Manage isolated memory scopes within the same database. Pages written with a namespace are invisible to queries that don’t specify it.

quaid namespace create project-alpha --ttl 720   # optional TTL in hours
quaid namespace list
quaid namespace destroy project-alpha             # removes the namespace and all its pages

Configuration

config

Read or write runtime config keys.

quaid config get default_token_budget
quaid config set default_token_budget 6000
quaid config reset default_token_budget

Subcommands: get <KEY> · set <KEY> <VALUE> · reset <KEY>.

See Configuration for the full key list.

System — serve, skills, raw

serve

Start the MCP stdio server. Connects any MCP client to this memory.

QUAID_DB=~/memory.db quaid serve

serve ships on macOS and Linux today; Windows parity is on the roadmap.

Flags (all require --http): --port <N> (default 3112) · --bind <ADDR> (loopback only in v1) · --token-file <PATH> · --trust-loopback.

daemon <run|install|uninstall|start|stop|restart|status|logs>

Background-daemon lifecycle. install writes a platform-native service unit (launchd on macOS, systemd on Linux) pointing at the active database, then starts it; run runs the daemon in the foreground (this is what the service unit invokes). run and install accept the same HTTP/SSE flags as serve.

quaid daemon install                 # install + start the background daemon
quaid daemon install --http --port 3112 --trust-loopback
quaid daemon status
quaid daemon logs

status

Process-level status: whether the daemon is installed/running, active MCP transports, and recent runtime activity. Distinct from quaid stats, which reports content-level statistics.

Flag	Type
--json	flag

skills

Skills are agent-shaped markdown files embedded in the binary, extractable to ~/.quaid/skills/, and overridable from the working directory.

quaid skills list      # show resolution order
quaid skills doctor    # verify hashes; report shadowing

Subcommands: list · doctor.

call <TOOL> [PARAMS_JSON]

Invoke a raw MCP tool from the CLI. Useful for debugging and for shell scripts.

quaid call memory_search '{"query":"alice","limit":3}'

pipe

JSONL streaming mode. Reads one JSON request object per line on stdin, writes one response per line on stdout. Designed for shell pipelines and lightweight harnesses.

version

Print the version and the memory’s schema-version state.

Exit codes

Code	Meaning
0	Success
1	General failure (validation, IO, business-rule violation)
2	Argument or flag parsing error

When --json is set, errors are also emitted as a JSON object with an error field on stderr.