vault-capture

Persist a memory to the vault so it can be retrieved in future sessions.

Mindset

Before capturing, answer two questions:

1. Is this time-bound? If yes → episodic. If no, continue.
2. Is this a how-to process? If yes → procedural. If no → semantic.

Always capture with --project when working in a project context. Always add --tags with at least two relevant keywords — they are the primary BM25 signal for future retrieval.

When to use

Use whenever the conversation produces:

• A confirmed decision ("we're using X instead of Y")
• A constraint that must not be violated
• A recurring bug or workaround
• A project convention or naming pattern
• A user preference expressed explicitly

How to use

vault-cli capture --text "<memory content>" [--tier episodic|semantic|procedural] [--project <id>] [--tags tag1,tag2]

Always double-quote the --text value to handle apostrophes and special characters.

Or pipe from stdin:

echo "<memory content>" | vault-cli capture

Tier selection

Examples

vault-cli capture --text "Decided to use Bun instead of Node for all scripts. Reason: workspace protocol support." --tier semantic --tags bun,tooling --project vault-core

vault-cli capture --text "Never use --force-push on main. CI enforces branch protection." --tier procedural --tags git,ci

vault-cli capture --text "Auth service fails silently when DB not ready — add depends_on with condition: service_healthy in docker-compose." --tier episodic --tags docker,auth,bug --project api

Never

• Never omit --tier for a rule or convention — defaulting to episodic means it will decay and be consolidated away
• Never capture without --tags — untagged memories score poorly in BM25 retrieval
• Never omit --project when working inside a project — global memories pollute cross-project searches
• Never use single quotes around --text — apostrophes in content will break the shell command