This page lists the broader Vault Agent Memory CLI surface. Most people should not memorize it. Start with the small human surface, then let agents and scheduled jobs use the wider toolbox.
For the compact map, run:
vault guide
vault guide --intent faq
vault guide --mode agent
vault guide --mode maintenanceSee also: docs/agent_first_usage.md.
| Intent | Command |
|---|---|
| Install or connect an agent | vault quickstart |
| Read beginner FAQ | vault guide --intent faq |
| See the small command map | vault guide |
| Browse locally | vault gui |
| Give agents one safe HTTP entrypoint | vault gateway serve |
| Self-host a central memory server | vault remote-server serve |
| Search memory | vault search "query" |
| Propose memory safely | vault remember "Title" --content "..." --reason "..." |
| Continue a task | vault task start/update/handoff |
| Check health | vault doctor / vault security doctor |
Use this surface when multiple agents, hosts, or devices share memory through a trusted central store. The older detailed commands remain available for scripts and debugging.
| Intent | Command |
|---|---|
| Start or orient | vault start |
| Run the daily memory loop | vault daily-loop run --write-report --json |
| Rebuild the latest daily-loop report without ingestion | vault daily-loop report --refresh --write-report --json |
| Check central sync state | vault memory-sync status --json |
| Submit candidate memory to the Supabase central inbox | vault memory-sync push --central-store --title "..." --content "..." --reason "..." |
| Submit candidate memory to a self-host inbox | vault memory-sync push --central-backend self-host --title "..." --content "..." |
| Pull central candidates into the local review queue | vault memory-sync pull --central-backend supabase --apply --json |
| Pull self-host central candidates into local review | vault memory-sync pull --central-backend self-host --apply --json |
| Dry-run one scheduled-sync pass | vault memory-sync run-once --push-read-copy --push-central-store --pull-candidates --dry-run --json |
| Run one trusted scheduled-sync pass | vault memory-sync run-once --push-read-copy --push-central-store --pull-candidates --apply --json |
| Preview candidate inbox migration between backends | vault memory-sync migrate-candidates --direction self-host-to-supabase --json |
| Export reviewed memory snapshots to a bundle | vault memory-sync export-snapshots --bundle ./vault-snapshots.json --json |
| Verify a snapshot bundle before DR import | vault memory-sync verify-snapshots --bundle ./vault-snapshots.json --require-content --json |
| Import a snapshot bundle as review candidates | vault memory-sync import-snapshots --bundle ./vault-snapshots.json --apply --json |
| Review candidates and conflicts | vault memory-review inbox --json |
| Run conservative review automation | vault memory-review run --mode conservative --json |
| Resolve a conflict explicitly | vault memory-review resolve <conflict_id> --action keep_active --reason "..." |
| Inspect lifecycle pressure | vault memory-lifecycle status --json |
| Run Dream as a report | vault memory-lifecycle dream --mode report --json |
| Preview archive / cold-store work | vault memory-lifecycle archive --json / vault memory-lifecycle cold-store --json |
| Run operations checks | vault ops status --json / vault ops doctor / vault ops security --json |
These commands are still useful, but they are mostly for agents, scripts, scheduled jobs, or explicit maintenance sessions.
| Command | Purpose |
|---|---|
vault init |
Initialize a project vault |
vault setup-agent / vault install-agent |
Run the agent installer wizard and optional Obsidian sync template generator |
vault remember "Title" --content "..." --reason "..." |
Propose candidate memory for review |
vault capture discover --pretty |
List likely session transcript exports without reading transcript contents |
vault capture session codex-session.jsonl --pretty |
Preview candidate memories extracted from an agent session transcript |
vault capture session codex-session.jsonl --write-candidates |
Write extracted session lessons into the candidate queue, not active knowledge |
vault memory pipeline --search-dir sessions --write-candidates --write-report |
Run the automatic conversation-memory pipeline: discover transcripts, extract lessons, gate them, write candidates, and leave a compact ingestion receipt |
vault task start "Ship feature" |
Create a Task Ledger working set for a long-running task without writing active knowledge |
vault task start "Ship feature" --priority P1 --due-at 2026-07-01 |
Create a task with explicit urgency and a due/reminder timestamp |
vault task update <task_id> --decision "..." --next-action "..." |
Update task-runtime state for handoff/resume; reusable lessons still go through candidates |
vault task update <task_id> --priority P0 --due-at 2026-06-30 |
Reprioritize the current working set without promoting it to long-term memory |
vault task handoff <task_id> |
Print a compact continuation note for the next agent/session |
vault memory temporal status / vault memory temporal list --state past |
Inspect current, past, future, and timeless fact windows |
vault candidates |
List pending candidate memories without dumping full raw content |
vault promote <candidate_id> --confirm |
Promote reviewed candidate memory |
vault compile |
Compile raw/ into SQLite and generated artifacts |
vault compile --no-embed |
Compile without optional embedding generation; recommended for the most portable first run |
vault search "query" |
Search the vault |
vault search "query" --exclude-expired |
Search currently valid temporal facts while keeping past facts available through temporal list |
vault map read <id> --lines 10-30 |
Read a bounded source range for citation |
vault gui |
Start the local read-only Vault Console |
vault gateway serve |
Start the token-protected HTTP Gateway for agent search, bounded read, and candidate-first memory submission |
vault gateway health --json |
Return machine-readable Gateway readiness without starting the HTTP server |
vault gateway openapi --json |
Return the stable Gateway HTTP contract for Coze, n8n, OpenClaw, and future remote adapters |
vault gateway serve --auth-token "$VAULT_GATEWAY_TOKEN" |
Use a stable token instead of printing a generated token at startup |
vault gateway serve --shutdown-timeout-seconds 30 |
Drain on SIGINT/SIGTERM: stop new requests and wait for active requests before exit |
vault gateway serve --allow-shared-candidates |
Allow agents to submit shared-scope candidates; they still do not write active knowledge |
vault remote-server health --json |
Check self-hosted remote-server readiness without starting the server |
vault remote-server openapi --json |
Return the same Gateway contract with self-hosted remote-server metadata |
vault remote-server serve --host 0.0.0.0 |
Start a self-hosted central memory entrypoint; requires VAULT_GATEWAY_TOKEN or --auth-token |
vault security doctor |
Check local GUI/MCP security posture plus Supabase service-role and self-host Remote Server boundary warnings |
vault remote status --json |
Offline check for local source-of-truth, Supabase read-copy/candidate-inbox setup, sync freshness hints, and Agent sharing policy files |
vault remote smoke --agent-id remote-agent --query "deployment SOP" --json |
Verify Supabase remote reader credentials and the vault_search_readable RPC |
vault remote doctor --agent-id remote-agent --query "deployment SOP" --json |
Diagnose the full Supabase remote reader path: search, readable-entry RPCs, Document Map, claims, content, map, and bounded read |
vault remote search "query" --agent-id remote-agent --json |
Search the Supabase read-only memory view through vault_search_readable |
vault remote map <id> --compact --json |
Inspect remote synced Document Map rows |
vault remote read <id> --node-uid <node> --json |
Read remote bounded evidence from synced content/claims |
vault remote submit-candidate --from-agent remote-agent --title "..." --content "..." --trust 0.8 --json |
Submit a remote candidate request through Supabase; does not write active knowledge |
vault remote pull-candidates --apply --json |
Trusted sync host pulls submitted remote requests into local memory_candidates |
vault remote pull-candidates --apply --auto-promote-low-risk --json |
Trusted sync host pulls remote requests and promotes only this pull's candidates that match automation_policy.yaml low-risk rules |
vault remote hmac-keys --json |
Show active remote candidate HMAC key ids for rotation without printing secrets |
vault sync revisions --json |
Inspect the local revision graph created by remote candidate imports and promotions |
vault sync conflicts --json |
List open local sync conflicts, such as same-title remote candidates that differ from active reviewed knowledge |
vault sync audit --json |
Inspect local sync audit events without reading private memory content |
vault sync resolve-conflict <conflict_id> --resolution keep_local --agent-id work-agent |
Keep local knowledge and reject the conflicting remote candidate |
vault sync resolve-conflict <conflict_id> --resolution accept_remote --apply-memory-change --agent-id work-agent |
Promote the remote candidate and archive the conflicting local row; old content stays auditable |
vault remove <id> --confirm |
Remove a knowledge entry after reviewing its ID |
| Command | Purpose |
|---|---|
vault add "Title" --content "..." |
Add one active knowledge entry directly |
vault add "Title" --file note.md |
Add an entry from a Markdown file |
vault import long-doc.md |
Import and chunk a long document |
vault import memory --source ./chatbox-export.json --format auto --dry-run --json --pretty |
Preview an external memory export from Chatbox, ChatGPT, Claude, Markdown, JSON, CSV, transcript, or OKF |
vault import memory --source ./chatbox-export.json --write-candidates --only summaries,decisions,preferences |
Write external memories into memory_candidates for review; never writes active knowledge directly |
vault import okf --bundle ./okf-bundle --dry-run --json --pretty |
Preview candidate-first import from an OKF-style Markdown bundle |
vault import okf --bundle ./okf-bundle --scope shared --owner-agent work-agent |
Write OKF concepts into memory_candidates for review, not active knowledge |
vault import obsidian --vault /path/to/ObsidianVault --dry-run |
Preview importing existing Obsidian notes into raw/obsidian/ |
vault import obsidian --vault /path/to/ObsidianVault --compile |
Import changed Obsidian notes and compile them into vault.db |
vault export obsidian --vault /path/to/ObsidianVault --dry-run --json |
Preview read-only Markdown notes for Obsidian browsing with machine-readable output |
vault export obsidian --vault /path/to/ObsidianVault --include-graph-overview --include-review-inbox |
Write Vault Home, Graph Overview, and review inbox notes so Obsidian can act as the human GUI |
vault okf validate ./okf-bundle --json --pretty |
Validate an OKF-style Markdown knowledge bundle before import, export, or publication |
vault export okf --bundle ./okf-bundle --dry-run --json --pretty |
Preview a read-only OKF-style export; private and restricted memories are excluded by default |
vault export okf --bundle ./okf-bundle --include-private --include-restricted |
Explicitly include protected memories when creating a private/internal bundle |
vault export markdown --bundle ./memory-md --dry-run --json --pretty |
Preview a batch Markdown export with one active memory per file plus manifest.json |
vault export json --bundle ./memory-json --json --pretty |
Write knowledge.json and manifest.json for machine-readable backup or migration work |
Prefer vault remember over vault add for autonomous agents or unreviewed
memory.
Prefer vault gateway serve when many local agents or scripts need the same
memory access pattern. Gateway keeps the public surface small:
/search, /read-range, /submit-candidate, /health, and /openapi.json.
It requires agent_id, hides private memory by default, writes only
candidates, and records compact audit rows in reports/gateway/audit.jsonl.
Use vault gateway health --json in installers and CI when you only need to
confirm the project vault is ready for Gateway clients.
Use vault gateway openapi --json when an adapter needs the request/response
shape without starting a server.
Use vault remote-server serve when the user wants a self-hosted central
memory host instead of Supabase. It reuses the Gateway contract, requires a
stable token, and still writes remote contributions as review candidates rather
than active memory.
Use vault import memory when moving memory from another product, an exported
chat transcript, a JSON/CSV archive, or a folder of Markdown notes. The import
is candidate-first: preview is the default, --write-candidates writes review
candidates, and promotion into active knowledge still requires the normal
review gates.
vault import obsidian skips .obsidian/, .trash/, .git/, and
00-Vault-Knowledge/ by default. The generated raw notes include
obsidian_source_path and obsidian_source_hash, so repeated imports update
changed notes without duplicating unchanged ones.
| Command | Purpose |
|---|---|
vault quickstart |
Small first-run wizard for agent-assisted users; asks only language, independent/shared memory, optional Obsidian/Supabase connections, and daily report time |
vault quickstart --non-interactive --project ~/Vaults/my-project --json |
Script the consumer defaults without exposing advanced setup-agent flags |
vault setup-agent |
Ask for scope, setup language, optional features, Obsidian import, sync templates, and generate agent-install/local-smoke.sh plus common Agent adapter startup templates |
vault setup-agent --non-interactive --agent codex --scope shared --agent-project-dir ~/Vaults/my-project --features core,mcp,obsidian_import |
Agent-friendly scripted install |
vault setup-agent --non-interactive --agent codex --scope shared --agent-project-dir ~/Vaults/my-project --memory-layout hybrid --features core,mcp --json |
Create a shared project vault plus private Agent vault and write hybrid-vault-layout.json |
vault setup-agent --non-interactive --agent codex --scope shared --agent-project-dir ~/Vaults/my-project --features core,mcp,semantic,supabase,headroom --language en --install-optional-deps --install-embedding-model mix --supabase-setup simple --json |
Install selected optional dependencies and configure a local semantic model |
vault setup-agent --non-interactive --agent maintenance-agent --scope shared --agent-project-dir ~/Vaults/my-project --features core,mcp,memory_agents --language zh-Hant --json |
Generate generic memory-maintenance guidance with report-only and candidate-only defaults |
vault setup-agent --non-interactive --agent profile-agent --scope shared --agent-project-dir ~/Vaults/my-project --features core,mcp,supabase --language zh-Hant --install-optional-deps --supabase-setup simple --supabase-sync cron --remote-reader all --json |
Generate guided Supabase setup, daily sync templates, and shell/n8n/Coze remote reader templates |
vault setup-agent --non-interactive --agent profile-agent --scope shared --agent-project-dir ~/Vaults/my-project --features core,mcp,supabase,memory_agents --agent-roster profile-agent:profile,work-agent:work,remote-agent:remote,n8n:automation --validation-pack all --json |
Generate a multi-agent access matrix plus live Supabase/n8n/Coze validation checklists |
vault setup-agent --non-interactive --agent codex --scope shared --agent-project-dir ~/Vaults/my-project --features core,mcp,supabase --write-stable-venv-script --json |
Generate agent-install/setup-stable-venv.sh for reboot-safe scheduled jobs and MCP commands |
vault setup-agent --non-interactive --agent automation-agent --scope shared --agent-project-dir ~/Vaults/my-project --features core,mcp,memory_agents --automation-schedule all --automation-mode balanced --automation-write-workspace --automation-include-transcripts --json |
Generate cron, LaunchAgent, and n8n templates for the candidate-first memory closed loop: pipeline, reflection, automation cycle, handoff, review-summary cards, and learning-health output |
vault setup-agent --non-interactive --agent automation-agent --scope shared --agent-project-dir ~/Vaults/my-project --features core,mcp,memory_agents --automation-schedule cron --automation-apply --automation-auto-promote-low-risk --json |
Write automation_policy.yaml for low-risk session-capture auto-promotion and generate a scheduled cycle that can apply it |
vault setup-agent --obsidian-vault ~/Documents/ObsidianVault --import-obsidian --obsidian-sync all |
Run first Obsidian import and write cron, LaunchAgent, and n8n templates |
vault update-status |
Show installed Vault version, local Agent registry, project vaults, per-Agent update notices, and startup handoff commands |
vault upgrade --check |
Check PyPI for a newer Vault release and print the correct pip, pipx, uv tool, or editable-install guidance without changing the environment |
vault upgrade --check --json |
Return the same check-only upgrade plan as machine-readable JSON |
vault upgrade --latest-version 0.10.2 |
Compare against a manually supplied version when PyPI is unavailable |
vault update-status --check-pypi --write-status --json |
Check PyPI for the latest release and write the machine-level update notice to ~/.vault-for-llm/update-status.json |
vault update-status --read-status --json |
Read the existing machine-level update notice without recomputing or contacting PyPI |
vault update-status --read-status --agent codex --json |
Read the shared notice and add a focused startup checklist for one Agent/runtime |
vault update-status --doctor --json |
Check whether the shared update notice exists, is fresh, includes every registered Agent, and shows runtime attention |
vault agent register --agent codex --project ~/Vaults/my-project --scope shared |
Manually register an Agent/runtime in the local multi-agent registry |
vault agent register --agent codex --project ~/Vaults/my-project --skills review-helper@1.0.0,task-helper |
Register which local skills this Agent expects, so update status can make skill usage visible |
vault agent list |
List Agents registered on this machine |
vault agent status --latest-version 0.7.21 |
Show the same registry/update status without contacting the network |
vault agent doctor --json |
Run the same shared update-distribution health check through the Agent registry namespace |
vault agent startup-doctor --template-dir ./agent-install --json |
Check generated startup contracts plus minimal Codex/Claude/Hermes/OpenClaw/Coze/n8n configs |
vault agent install-runtime-template --runtime codex --target ./AGENTS.md |
Preview applying the generated Codex startup template into a runtime instruction file |
vault agent install-runtime-template --runtime codex --target ./AGENTS.md --apply |
Apply the marked startup block and create a backup before changing an existing file |
vault quickstart is the preferred first-run command for new users. It wraps the
consumer setup path and deliberately hides the advanced feature matrix.
vault install-agent is an alias for vault setup-agent.
Interactive setup asks before installing optional dependencies. Non-interactive
agents must pass --install-optional-deps; semantic model download is opt-in
with --install-embedding-model zh|en|mix.
vault setup-agent also registers the Agent in
~/.vault-for-llm/agent-registry.json, so other local runtimes can discover the
same project vault and startup handoff path through vault update-status.
The status payload includes agent_update_notices; if one Agent updates Vault
and writes status, other local runtimes can see whether their registered
environment is behind the current or latest known version.
Use vault agent doctor after upgrades to verify the shared notice is fresh and
all registered runtimes appear in the update notice.
vault upgrade is intentionally check-only in this release. It never invokes a
package manager or migrates a database; review and run the recommended command,
then use vault --version and vault doctor to verify the upgraded runtime.
MCP-capable runtimes can call vault_update_status and
vault_automation_handoff from the core profile for the same startup path.
They can also call vault_update_status with doctor=true and their
agent_id for the same update-distribution health check without adding another
MCP tool.
vault agent install-runtime-template is dry-run by default. It writes a marked
Vault block only with --apply, replaces that block on later runs, and creates
a .bak.<timestamp> backup for existing target files unless --no-backup is
used.
The default memory layout is hybrid: setup creates the shared project vault
plus a private Agent vault under ~/Vaults/agents/<agent>/private-memory, then
writes agent-install/hybrid-vault-layout.json.
Use --write-stable-venv-script for the default long-lived venv path, or
--stable-venv PATH when the user chooses a custom stable virtualenv.
Memory-maintenance guidance is opt-in with the compatibility feature ID
--features memory_agents; it writes README-memory-agents.md and does not
install a model, auto-promote memory, or construct identity/personality/
relationship/life-phase/human models.
Memory automation templates can opt into transcript ingestion with
--automation-capture-transcripts; use it together with --automation-apply
only when scheduled jobs are allowed to read discovered transcript files and
write review candidates.
Supabase sync templates are opt-in with --supabase-sync cron|launchagent|n8n|realtime|all
and use python -m scripts.sync_to_supabase --db <project>/vault.db.
The consolidated Central Memory Station worker is vault memory-sync run-once
or python -m scripts.central_memory_sync; it writes
reports/central-memory-sync-latest.json, can push the reviewed read copy with
--push-read-copy, can write Central Memory Station tables with
--push-central-store, can write reviewed safe-summary embeddings into the
central pgvector table with --push-central-vectors, and can pull central
candidates into local review with --pull-candidates --apply. Use
--central-backend self-host when the
candidate inbox is local vault-central.db behind Gateway / Remote Server
instead of Supabase. For one-off Supabase candidate submissions,
vault memory-sync push --central-store ... writes the new
vault_memory_candidates_central inbox; omitting --central-store keeps the
older guarded RPC path for compatibility.
vault memory-sync migrate-candidates --direction supabase-to-self-host|self-host-to-supabase
copies only pending Central Memory Station candidate inbox rows between backend
adapters. It previews by default and requires --apply before writing the
target inbox. It does not migrate active memory, local review candidates, or
promotion decisions.
vault memory-sync export-snapshots --bundle ./vault-snapshots.json writes a
reviewed active-memory snapshot bundle. By default the bundle excludes raw
memory content; --include-content should be used only on a trusted, encrypted
transfer path. The bundle includes a manifest with snapshot count, snapshot
digest, content policy, and metadata-only local revision/audit counts.
vault memory-sync verify-snapshots --bundle ./vault-snapshots.json validates
the bundle manifest and content hashes without writing memory; add
--require-content before a disaster-recovery candidate import.
vault memory-sync import-snapshots --bundle ./vault-snapshots.json
previews by default and, with --apply, writes local memory_candidates only.
It does not write active knowledge, does not promote candidates, and does not
turn the target backend into a multi-master memory database.
When setup-agent generates Supabase sync templates, it also writes
central-memory-sync.cron, com.zycaskevin.vault-for-llm.central-memory-sync.plist,
n8n-central-memory-sync.workflow.json, and README-central-memory-sync.md for
the 30-60 minute Central Memory Station loop.
Use realtime only when the local machine is trusted to hold a service-role
key; it runs python -m scripts.watch_supabase_sync and pushes local changes
after a short debounce.
Supabase remote reader templates are opt-in with
--remote-reader shell|n8n|coze|all; validate credentials with
vault remote smoke --agent-id <agent> --json.
Before live validation, run vault remote status --json from the project vault.
It does not contact Supabase. It tells agents that the local SQLite vault is the
source of truth, Supabase is a reviewed read copy plus candidate request inbox,
near-realtime active-memory sync is still one-way local-to-Supabase push, and
remote freshness is unknown unless a local sync report exists.
Remote candidate sync is intentionally candidate-first: hosted agents use
vault remote submit-candidate with anon/publishable credentials, while a
trusted local host uses vault remote pull-candidates --apply with the service
role key to write local memory_candidates, not active knowledge.
--auto-promote-low-risk is available only with --apply; it still requires
automation_policy.yaml, passing gates, allowed source/type/scope/sensitivity,
trust above threshold, and a source reference.
vault sync revisions/conflicts/audit is the local safety surface for the next
multi-host phase. It records what arrived, what was promoted, what conflicted,
and who marked a conflict resolved. accept_remote requires
--apply-memory-change because it changes active memory by promoting the remote
candidate and archiving the local row. This is still candidate-first sync, not
multi-master active-knowledge sync.
Multi-agent roster templates are opt-in with --agent-roster; each entry uses
agent_id:role[:scope[:max_sensitivity]], for example
profile-agent:profile,work-agent:work,remote-agent:remote,n8n:automation.
Allowed roles remain work, profile, care, dream, remote,
automation, and observer for compatibility. The profile/care/dream names
are access labels, not Vault-owned modeling domains. Live external validation
files are opt-in with --validation-pack remote|n8n|coze|all.
Memory automation schedule files are opt-in with
--automation-schedule cron|launchagent|n8n|all; generated jobs default to
vault daily-loop run and stay report-first unless --automation-apply is
explicitly set. Use --automation-command run for maintenance-only schedules.
Add --automation-write-workspace when those scheduled cycle jobs should write
reports/automation/cycle-latest.json and reports/automation/cycle-latest.md
as the next-agent workbench.
Generated memory automation jobs also write
reports/automation/pipeline-latest.json plus .md,
reports/automation/review-summary-latest.json plus .md, and
reports/automation/learning-health-latest.json and .md after each pass.
Add --automation-include-transcripts when those scheduled jobs should write
metadata-only uncaptured transcript hints into the inbox handoff.
Add --automation-auto-promote-low-risk when setup should write the narrow
low-risk auto-promote policy; pair it with --automation-apply for scheduled
promotion, otherwise scheduled runs preview only.
Manual interactive setup asks for en, zh-Hant, or zh-CN; non-interactive
agent installs can pass --language. Supabase setup guide generation is opt-in
with --supabase-setup none|simple|advanced; keep simple as the default path
unless the user asks for RLS or multi-agent permissions.
For MCP remote readers, use vault-mcp --tool-profile remote and the sequence
vault_remote_search -> vault_remote_map_show -> vault_remote_read_range
after applying docs/supabase_read_policy.sql in Supabase.
Remote IDs can be local integers or Supabase UUIDs; pass the ID returned by
search directly into map/read.
Use vault remote doctor --agent-id <agent> --json when search works but
map/read fails, or after applying remote-reader SQL. It returns safe status
checks, counts, and next actions without dumping raw synced content.
For per-tool MCP examples, see docs/mcp_tool_reference.md.
| Command | Purpose |
|---|---|
vault search "query" |
Search the vault; use --min-score to tune weak-match suppression |
vault search "query" --json |
Return machine-readable search results for agents, scripts, and automation smoke tests |
vault search "query" --graph-expand 2 |
Search with graph expansion |
vault map build |
Build/backfill Document Map rows |
vault map show <id> |
Show a knowledge entry's section map |
vault map read <id> --lines 10-30 |
Read a bounded source range |
vault map build/show/read/query ... --json |
Return machine-readable Document Map status, nodes, bounded lines, or claim matches |
vault list |
List knowledge entries |
vault remove <id> --confirm / vault delete <id> --confirm |
Delete a knowledge entry by ID |
vault stats |
Show vault statistics |
vault usage stats / vault usage archive-expired --apply |
Inspect retrieval usage and archive expired unused memories without deleting them |
vault usage cold-store-expired --apply |
Summarize and archive expired-but-used memories; skips private/high/restricted/L0/L1 rows and retains original content |
Task Ledger is the task-runtime workbench. It is not L2, not L4, and not
active knowledge. Use it to keep long-running tasks resumable across Codex,
Hermes, Claude Code, OpenClaw, or other agents without dumping whole chat
history into the context window.
| Command | Purpose |
|---|---|
vault task start "Repair benchmark" --plan "inspect failing tests" --next-action "run focused pytest" |
Create a task working set |
vault task start "Repair benchmark" --priority P1 --due-at 2026-07-01 |
Create a task with urgency and a due/reminder timestamp |
vault task update <task_id> --done "schema added" --decision "Task Ledger is not L2" |
Append completed work and hard decisions |
vault task update <task_id> --priority P0 --due-at 2026-06-30 |
Change task urgency without touching active memory |
vault task update <task_id> --blocker "waiting for CI" --question "sync task fields to Supabase?" |
Track blockers and open questions |
vault task status <task_id> --json |
Read the current working set for an agent |
vault task status --status active |
List active task ledgers |
vault task resume <task_id> |
Alias for reading one task with resume semantics |
vault task handoff <task_id> |
Print compact Markdown for the next agent/session |
vault task send-handoff <task_id> --from-agent codex --to-agent hermes --message "continue from tests" |
Create a directed handoff packet in the shared task inbox |
vault task inbox --agent-id hermes |
List pending handoff packets addressed to an agent |
vault task claim-handoff <handoff_id> --agent-id hermes |
Mark a handoff as claimed by the receiving agent |
vault task complete <task_id> --summary "..." |
Mark the task completed without promoting task events |
At task phase end, extract only reusable lessons with the normal candidate-first
workflow. Failed attempts and temporary task events should remain task history,
not knowledge rows.
Task lists sort by priority first (P0 to P3), then by due date, then by
recent updates. Use P0 for active incidents, P1 for urgent release/blocking
work, P2 for normal planned work, and P3 for backlog or optional follow-up.
Directed handoff packets are the local multi-Agent handoff protocol. They are task-runtime inbox items, not private memory sharing. A sender can address a handoff to another agent, the receiver can claim it, and the task event log keeps the audit trail. The packet contains the task snapshot and sender note; it should reference shared evidence instead of copying another agent's private memory.
The local Skill registry stores the latest skill row plus revision history. It is for agent capability handoff and upgrade planning, not for silently changing an agent's runtime.
| Command | Purpose |
|---|---|
vault skill push --file SKILL.md --name review-helper --version 1.0.0 |
Register one Skill and store its first revision |
vault skill push --file SKILL.md --name review-helper --version 1.1.0 |
Publish a newer local revision and make it the latest version |
vault skill versions review-helper |
List known versions without raw Skill content |
vault skill diff review-helper --from-version 1.0.0 --to-version 1.1.0 |
Compare compact metadata/content hashes between two versions |
vault skill upgrade-plan --installed '{"review-helper":"1.0.0"}' --json |
Compare caller-installed skill versions with the registry latest versions |
vault skill upgrade-plan --installed-file installed-skills.json --outdated-only |
Compare an installed Skill manifest and show only upgrade/drift/local-newer items |
vault skill pull review-helper |
Write the latest Skill content into the local skills cache |
MCP exposes Skill tools outside core; this keeps daily agent startup small.
review can inspect versions, upgrade plans, and sync manifests. maintenance
and full can also use permission-gated registry writes:
vault_skill_pushwrites or revises a Skill in the local registry only.vault_skill_sync_manifestgives trusted sync workers hashes and metadata, and exports bounded content only when explicitly allowed.vault_skill_mark_syncedrecords that an external sync worker succeeded.
These MCP tools do not install, overwrite, or delete runtime Skill files. Agent runtime updates still require an explicit user/operator-approved installer or adapter step.
Installed manifests may use either compact versions:
{"review-helper": "1.0.0"}or version plus content hash:
{"review-helper": {"version": "1.0.0", "content_hash": "abc123"}}The richer form lets Vault distinguish normal upgrades from same-version content drift.
| Command | Purpose |
|---|---|
vault lint |
Run quality checks |
vault dream |
Produce report-first memory curation summaries |
vault candidates --include-gates |
Review candidate-memory queue and gate details before promotion |
vault candidate-review <id> --outcome rejected --reason "..." |
Record rejected/blocked candidate feedback without promoting memory |
vault capture session <transcript> --write-candidates |
Capture decisions, pitfalls, workflows, and source-of-truth lines from JSONL/Markdown/text transcripts as gated candidates |
vault memory reflection --write-candidates |
Run Dream plus lifecycle automation as a report-first reflection pass |
vault daily-loop run --write-report |
Run the safe daily memory loop: sync dry-run/freshness, automation cycle handoff, inbox, review-summary, learning-health, and the human daily report |
vault daily-loop report --refresh --write-report |
Rebuild reports/daily-loop/daily-loop-latest.* from read-only status surfaces without capture, reflection, sync writes, or new candidate writes |
vault automation plan --write-policy |
Create a policy-based maintenance plan and starter automation_policy.yaml |
vault automation run / vault automation run --apply |
Run report-first memory automation; reports include a dry-run diff and action ledger, and --apply only performs policy-allowed reversible actions or explicit low-risk auto-promote matches that are not downgraded by learned review feedback |
vault automation cycle --apply |
Run one safe feedback-to-curation loop: evaluate reviewed candidate outcomes, write learning_policy.json, then run policy-based automation so Dream can consume the latest hints |
vault automation cycle --write-workspace --include-transcripts |
Write reports/automation/cycle-latest.json and .md: compact candidate review, metadata-only transcript paths, priority brief, suggested next tasks, and learning-policy summary for the next agent |
vault automation activity --pretty |
Show a compact read-only activity feed for recent auto-promote previews, promotions, and skipped reasons |
vault automation brief --pretty |
Show one compact intelligence brief: learning hints, explainable memory importance, forgetting pressure, shared agent health, and the 5% human-review queue |
vault automation brief --write-brief |
Write reports/automation/brief-latest.json and .md for dashboards or the next agent |
vault automation review-summary --write-summary |
Write the shortest human approval cards to reports/automation/review-summary-latest.json and .md |
vault automation review-feedback --kind memory_importance --card-id 12 --decision accept --reason "Correct card" --write-learning-policy |
Record feedback for one review-summary card, refresh bounded learning hints, and rewrite the next review-summary plus learning-health reports |
vault automation learning-health --write-health |
Write a compact dashboard-safe health panel for feedback learning to reports/automation/learning-health-latest.json and .md |
vault automation fleet-health --write-health |
Write a shared multi-Agent automation health panel to reports/automation/fleet-health-latest.json and .md |
vault automation handoff |
Print the latest compact automation handoff for the next agent; surfaces fleet-health-latest first when present, then prefers cycle-latest.md |
vault automation inbox --limit 5 --write-handoff |
Show the shortest read-only review queue and write reports/automation/inbox-latest.json |
vault automation inbox --include-transcripts --write-handoff |
Add metadata-only uncaptured transcript hints to the inbox handoff |
vault automation report / vault automation eval --write-learning-policy / vault automation doctor |
Review automation reports, evaluate candidate-outcome feedback into bounded curation hints, and check scheduled-job readiness |
vault freshness |
Experimental freshness/review scheduling |
vault usage archive-expired |
Preview TTL-based archive actions; add --apply to mark eligible memories archived |
vault usage cold-store-expired |
Preview summarize-then-cold-store actions for expired-but-used memories; add --apply to write summaries and archive eligible rows |
vault dedup |
Detect or merge duplicate entries |
vault converge |
Experimental convergence/self-questioning check |
vault cross-validate |
Experimental cross-model validation |
vault search-qa run / vault search-qa compare |
Run Search QA snapshots, hard-negative checks, and before/after comparisons |
| Command | Purpose |
|---|---|
vault doctor |
Check local environment and optional dependencies |
vault doctor --json |
Return machine-readable environment checks with top-level ok, status, and next_action |
vault db status / vault db migrate |
Inspect or update local SQLite schema |
vault db backup / vault db verify-backup / vault db restore |
Create, verify, and restore local SQLite backups |
vault graph build / vault graph show |
Build or inspect the inferred knowledge graph |
vault graph build/show --json |
Return machine-readable graph build results or graph summary |
| Command | Purpose |
|---|---|
vault install-embedding |
Install a local embedding model |
vault config set embedding.provider ollama |
Configure an embedding provider; also supports openai, cohere, and voyage when the matching API key environment variable is set |
vault semantic rebuild |
Rebuild semantic vector rows after configuring a real embedding provider |
vault semantic rebuild --changed-only --persist-cache |
Refresh only missing or stale semantic vector rows |
vault semantic warm |
Precompute QA query embeddings without writing vector rows |
vault semantic smoke |
Rebuild, warm, and run a Search QA smoke snapshot |
vault semantic cache-stats / vault semantic cache-prune |
Inspect or prune the durable embedding cache |
vault semantic startup / vault semantic daemon |
Run startup or bounded daemon lifecycle hooks |
| Command | Purpose |
|---|---|
vault skill search "query" |
Search local experimental skill registry entries |
Run vault <command> --help for command-specific options.