CLI reference

Everything memd does is a subcommand on the same binary. Commands fall into three groups: agent-facing (the retrieval and write commands agents run every session), administrative (init, maintenance, stats, exports), and structured operations (memd call <operation> and memd batch --jsonl).

Agent-facing commands

For write-quality expectations and cleanup safety, see the Operational contract.

Command	Purpose
memd agent-context	Prefetch bounded context to a file with audit logs.
memd search	Direct compact search.
memd add	Store summaries, traces, evidence, decisions.
memd warm start \| status \| stop	Manage the private local warm worker used by --warm auto\|required.
memd batch --jsonl	Run structured operation calls from JSONL in one loaded process; --stream keeps stdin/stdout open for benchmark clients.
memd get, memd delete, memd stats	Inspect and maintain chunks.
memd export, memd export-markdown, memd export-omf, memd import-omf	Portable local memory operations.
memd init	Write .memd/ scope files and CLI guardrail blocks.
memd doctor	Diagnose binary discovery (incl. PATH-binary version skew), the resolved --data-dir, warm-worker reachability and worker-vs-CLI version skew, global agent rules, Claude Code SessionStart hook, and current project scope; --strict exits 2 when any check fails.
memd memory-md	Refresh project-root memory.md with ranked fact libraries for session-start use.
memd eval-memory-md	Gate startup-memory quality with --min-useful-ratio, --max-generated-wrappers, and optional --agent-usefulness.
memd eval-retrieval	Gate retrieval quality with precision, hit-rate, recall, and MRR thresholds.
memd eval-write-quality	Gate write admission, duplicate reuse, storage growth, and retention compaction.
memd audit	Report tenant/project storage shape, generated-wrapper noise, alias groups, unreadable active rows, and routine progress summaries that still lack an expiry; --strict exits 2 when unreadable_active_chunks > 0.
memd report	Usefulness and self-diagnosis report from the usage ledger and store metadata; --strict exits 2 on any [warn] line.
memd cleanup-plan	Generate a non-destructive cleanup approval report with archive/purge command previews and post-cleanup pass criteria.
memd purge	Dry-run or archive-first cleanup of hidden rows; --apply verifies the archive before mutation, and --include-unreadable-active previews active metadata rows whose segment payload cannot be loaded.
memd purge-archive	Read-only verification for memd purge --archive files: validates format/counts/payload flags, emits SHA-256, and can enforce expected tenant/project.
memd consolidate	Call the configured LLM (Claude Haiku or Codex Spark, selected by MEMD_CONSOLIDATOR) and stage validated output under a journaled run ID. Candidate summaries remain hidden until review. --promote requests promotion in the same run; --legacy-immediate is a deprecated alias for one compatibility release. Exact source-set reruns reuse the existing run.
memd consolidate-review	List staged runs, accept one for atomic promotion, or reject it while leaving every source active.
memd session-start	Auto-create a minimal .memd/project_scope.json when missing, recover consolidation runs idle for at least 30 seconds, refresh memory.md synchronously, then stage a background consolidation when enough chunks have accumulated. Recovery promotes only runs with durable promotion intent. A writer-lock failure is reported in consolidation_recovery without suppressing context refresh. Wired into Claude Code via the bundled skill installer; a Codex hook template lives at memd-skill/examples/codex_session_start_hook.json.
memd eval-counterfactual	Replay a JSONL benchmark file; write an overlap@k / rank-shift report under evals/bench/reports/. Monitors whether kind:consolidated lessons are load-bearing in retrieval.
memd eval-outcome-ranking	Compare the served order with the source-deduplicated outcome-v1 shadow order against JSONL relevant/harmful judgments. Writes JSON and Markdown counterfactual reports without activating the policy.
memd maintenance	Disk hygiene: sweep orphan HNSW snapshots; --aggressive also force-merges the Tantivy sparse index and reports before/after segment counts.

memd add returns the primary chunk_id and stored_chunk_ids, an ordered list of every physical chunk created by document splitting.

• memory-md --explain-output <path> writes a JSON candidate audit with query source, score components, tags, display/filter decisions, structured project state, and agent-usefulness metrics.
• memory-md renders a scope line and Memory health before the fact libraries. It omits task, handoff, and git state by design: those have repo homes. Takeaways already covered by a repo file are suppressed, and warnings for scope drift or unreadable memory payloads. Missing or unreadable task files are reported as unknown; they are not treated as proof that no work is open.
• Project and machine-wide candidates are assigned and deduplicated as one bounded pool before display limits are applied. Exact IDs, consolidation lineage, and high-confidence topic matches appear in one section only, with the active project's section taking precedence.
• eval-memory-md --agent-usefulness fails when startup context lacks current state, git state for a git repo, source-backed next actions when open tasks exist, a readable task source, scope-health warnings, or when displayed startup items include continuation fragments or generated boilerplate actions. --gold-file can run the same checks over local multi-project fixtures.
• eval-retrieval gates with --min-precision-at-k, --min-hit-rate-at-k, --min-known-recall-at-k, and --min-mrr.
• eval-outcome-ranking --queries <jsonl> --report-json <path> records normal privacy-safe episodes but does not serve the shadow order. Each query row contains id, query, relevant_chunk_ids, and harmful_chunk_ids. Existing report paths are never overwritten. Its served baseline is the current production order, including any exact-query relevance feedback in the store; the shadow order adds outcome-attributed priors.
• search episodes retain the expanded candidate pool and counterfactual shadow ranks. Multi-query agent-context episodes retain only the final merged result set and use ranking mode off; they support later outcome attribution but are not valid counterfactual ranking records.
• task_id, thread_id, and outcome evidence references are plaintext linkage fields. Keep them opaque and non-sensitive. Retrieval episode tables store query hashes rather than raw queries, but an explicit agent-context --log-dir audit log includes the raw query summaries.
• eval-write-quality gates with --min-rejection-or-downgrade-rate, --min-duplicate-reuse-rate, --max-total-chunks, --max-disk-bytes, and --require-retention-compaction.

Consolidation review

The default command creates a hidden, validated proposal and returns its run_id, candidate IDs, consolidator command, model, and version:

memd consolidate --project-dir .
memd consolidate-review --list
memd consolidate-review <run_id> --accept

Use --reject instead of --accept to close the run without changing its sources. Acceptance records durable promotion intent before the atomic transaction. A restart can therefore finish an accepted run, but cannot promote a proposal that was only staged. Project-scoped acceptance promotes the candidates and marks same-project sources Superseded; tenant-wide acceptance records derives_from lineage and leaves project sources active.

For an explicitly automated workflow, use:

memd consolidate --project-dir . --promote

The deprecated --legacy-immediate flag has the same promotion semantics and prints a warning. It exists only for migration from the former default.

Each proposed entry must name a concrete agent action, cite exactly the source IDs it supersedes or derives from, and provide a confidence in [0, 1]. Malformed, conflicting, or prompt-like output is rejected before candidate creation. The journal records the consolidator identity and points to a permission-restricted, size-capped raw-response audit artifact inside the store data directory. Candidate contents and audit artifacts are never part of retrieval or export surfaces.

Structured operations (memd call)

memd call <operation> --json ... exposes the historical operation surface through the executable without starting a separate integration process. This is the compatibility path for advanced scripts that need structured task, artifact, context, code, or debug operations before every operation gets a dedicated first-class subcommand.

When the current directory is inside a repository with .memd/project_scope.json, memd call and memd batch add the scope's tenant_id and project_id to requests that omit tenant_id. A request with an explicit JSON tenant_id does not inherit the repository project; include project_id in that request when project filtering is intended. Scope is resolved before warm-worker routing. A malformed or unreadable scope file fails closed for requests without a tenant. In batch mode, --continue-on-error reports that failure on the affected line while explicitly scoped lines continue.

memory.* — raw searchable content

• memory.add — single chunk. The response contains the primary chunk_id and stored_chunk_ids, an ordered list of every stored split child with the primary ID first. Code chunks with a real source.path are parsed into the structural index.
• memory.add_batch — many chunks in one call. Its chunk_ids array contains one primary ID per logical input, preserving input order. It does not expose split-child IDs; use individual memory.add calls when physical write identity is required for retrieval or outcome attribution.
• memory.search — hybrid retrieval with optional mode, project_id, compact/token-budgeted output, and event sibling expansion.
• memory.get, memory.delete, memory.stats, memory.health, memory.metrics.
• memory.compact — explicit digest refresh; supports digest_modes and force_digest_rebuild.
• memory.dream — dry-run-first retention and compaction planning; safely retires duplicate digest projections on apply and writes a traceable report. Exact duplicate raw chunks are reported by health but not auto-retired by the safe profile.

Conversation-style chunks can carry caller-supplied event:<id> tags along with entry:factual or entry:relational. Passing expand_event_siblings: true to memory.search keeps the ranked result list unchanged and attaches bounded same-tenant/same-project chunks that share the matched event tag under each result's expanded_siblings field.

task.* — structured work

• task.start (only goal required), task.progress, task.finish.
• task.run_start / task.run_finish for substantive runs.
• task.add_evidence for concrete evidence against a task.
• task.get, task.search, task.resume.

artifact.* — focused collaboration tools

Artifact collaboration uses four specialized tools with tight schemas:

• artifact.review — request a review; attach summary and requested action.
• artifact.revision — supersede a prior artifact with superseded_by lineage.
• artifact.decision — choose between alternatives with why_chosen.
• artifact.verification — distinct-writer countersignature; with a different agent_id than the parent's and supports_claim = true it promotes the underlying claim to VerifiedRecord trust.

Inspection and retrieval:

• artifact.get, artifact.search, artifact.list_thread.
• artifact.find_related (retrieval helper; former artifact.verify alias is deprecated but still works).
• artifact.find_failures, artifact.find_decisions, artifact.find_evidence, artifact.find_highlights.

artifact.create remains available for backwards compatibility with a deprecation warning. Digest artifacts are system-generated and cannot be forged through artifact.create.

artifact.search defaults to the full legacy response. Passing compact: true adds budget_info; include_artifact: false and include_matched_text: false return only identifiers, summaries, ranking, and trust/grounding metadata so a caller can fetch selected records with artifact.get.

code.* — structural navigation

code.find_definition, code.find_references, code.find_callers, code.find_imports. Index source by calling memory.add with type = "code" and a real source.path.

context.* — summary-first retrieval

context.brief_project, context.find_relevant_context, context.get_hot_context, context.get_files_for_subsystem, context.list_subsystems, context.suggest_agent.

context.find_relevant_context can prepend hot-context chunks when include_hot is true. That legacy hot pre-scan is bounded by a short wall-clock budget so large tenants still fall through to normal retrieval instead of blocking the whole lookup on a full payload scan.

Warm and batch execution

For sustained local use, the warm worker keeps the store and indexes hot across CLI calls. Warm-routable write commands route through the worker by default, so the worker is the normal single-writer path:

memd warm start
memd agent-context --warm required --tenant-id quickstart --query "..."
memd warm stop

Flags:

• --warm auto (default) — use the local worker, starting it if needed; fall back to the current CLI process if startup or connection fails.
• --warm off — always run in the current CLI process.
• --warm required — require a local worker; fail if it cannot be started or reached, and hard-error on cold-only variants.

Routable commands: see Shared topology.

For scripts that need many structured operations in one loaded process:

memd batch --jsonl requests.jsonl
memd batch --jsonl - --stream

Each JSONL line should contain {"tool":"memory.search","arguments":{...}}; the command emits one JSON result row per input line.

See Quick start for end-to-end examples and Configuration for the environment variables that change defaults.