Empirical Docs / CLI Reference

Memory commands.

Turn decisions, preferences, and project context into durable memory that every connected tool can recall.

Why Empirical memory exists

Chat context disappears when you change tools, projects, or sessions. Empirical gives that context a durable home, then scopes and retrieves it when an agent needs it. Store decisions, constraints, preferences, and concise project facts—not a transcript of every conversation.

  • Personal preferences that should follow you
  • Workspace-specific decisions and constraints
  • Handoffs another agent should be able to recover

Read memory

Query is the normal natural-language entry point. Use get when automation already knows the ID, and list for a filtered or paginated inventory. Add --path to a query when you want to force one retrieval pathway instead of letting Empirical choose.

empirical memory query --match "What are this project's deployment constraints?" --top-k 8 --pretty
empirical memory get --memory-id <id> --pretty
empirical memory list --category project --limit 20 --pretty

Write memory

Record a standalone memory when the information can be understood later without the original conversation. Note appends context to an existing record; update changes its durable fields.

empirical memory record --category decision --summary "Deploy docs from main after the build passes"
empirical memory note --match "Deploy docs from main" --text "FTP upload remains a separate release step"
empirical memory update --match "Deploy docs" --patch-json '{"summary":"Deploy docs from main after build and upload verification"}'

Files on a memory

A memory can carry files: the signed contract behind a decision, the screenshot behind a bug, the PDF behind a note. Up to 20 files per memory, 25MB each. Deleting one is reversible for 30 days, and the response always tells you the date the bytes are actually removed.

  • empirical memory attachment list — what is attached, with size, type and date. Add --include-deleted to see files still inside the restore window
  • empirical memory attachment add — attach a local file
  • empirical memory attachment get — download one. --out takes a path or a directory, and an existing file is never overwritten without --force
  • empirical memory attachment delete — a soft delete, and a dry run unless you pass --confirm
  • empirical memory attachment restore — undo that delete inside the window
  • empirical memory attach and empirical memory attachments are shorthands for add and list
empirical memory attach --memory-id <id> --file ./contract.pdf
empirical memory attachments --memory-id <id> --format table
empirical memory attachment get --memory-id <id> --attachment-id <att>

What this needs: Attachments are a paid feature: the free tier has no attachment storage and an upload is refused with an upgrade link. Every subcommand also takes --match <query> instead of --memory-id when you know what the memory is about but not its id.

Documents from a tree

When items nest — an idea with sub-ideas, and sub-ideas under those — you can pull the whole thing out as one readable document instead of walking it a level at a time. The server assembles it in a single query and returns markdown, in the order the tree is actually arranged.

  • Markdown is the default output here, unlike other memory subcommands, because the point of this one is something to read
  • --depth limits how far down it goes, --max-nodes caps the size, and --no-notes gives a bare outline
  • --out <path> writes the document to a file; --format json returns the nodes for scripting
  • If a cap cuts the document short it says so on stderr, so a redirected file stays clean
empirical memory tree --memory-id <id> --out idea.md
empirical memory tree --match "retention programme" --depth 2 --no-notes

Where nesting comes from: Items nest only in a workspace that has a shape. For an ordinary memory this returns that one memory as a one-section document, which is the answer rather than an error.

Maintain and export

Use delete only when a record is genuinely obsolete, review duplicate candidates before merging, and export before a migration or major cleanup.

empirical memory duplicates --memory-id <id>
empirical memory merge --canonical-id <canonical-id> --duplicate-id <duplicate-id>
empirical memory delete --match "obsolete preference" --confirm
empirical memory export --scope personal --out ./empirical-memories.json

Last updated: July 31, 2026