CLI Reference

The strata CLI is your one-stop shop for everything memory-related - whether you're a carbon-based lifeform or a silicon-based agent running on tokens. This page documents every command, its arguments, options, and what you can expect it to do. We're thorough, but not humorless.

Global Flags

These flags work with any command. Consider them the universal remote for Strata.

Flag Description
--json Output results as JSON (for scripting). Applies to all commands.
--agent Alias for --json. Same behaviour.

When --json or --agent is active, all output becomes a single JSON object with status, command, data, and duration_ms fields. Errors follow the same format with status: "error" and exit code 1. Your scripts will thank you.

Commands

SETUP

strata init

Create a new Strata data directory.

Purpose: Bootstraps the directory structure for all three strata - no existential questions asked. Creates active/, cooled/, and archive/ directories, sets up sensible defaults (projects/, entities/, gtd/), generates your first index.md, and gently asks which search backend you'd like.

Usage:

strata init                    # Creates ./strata_data/ (project-local, default)
strata init --local            # Explicit project-local (same as default)
strata init --global           # Creates ~/.strata/ (global)
strata init --non-interactive  # Skip QMD onboarding prompts

Notes:

  • Interactive by default - prompts to choose search backend (QMD hybrid, QMD + reranker, or FTS5 keyword)
  • If QMD is selected, attempted auto-install via npx with 30s timeout
  • Configuration is persisted to strata.json

strata config

View or modify configuration.

Purpose: Peek under the hood or tweak settings without digging through config files. Show everything, grab a single value, or set something new - all from the command line.

Usage:

strata config                          # Show all configuration
strata config get <key>                # Get a specific value
strata config set <key> <value>        # Set a specific value

Examples:

strata config get decay_thresholds.projects
# Output: 14

strata config set decay_thresholds.projects 21
strata config set lru_days 60
strata config set search_backend fts5

Notes:

  • Keys support dotted paths for nested fields (e.g., decay_thresholds.projects)
  • Values are auto-parsed: integers, floats, booleans, JSON, or plain strings
  • Changes persist to strata.json immediately
  • JSON mode: strata config --json

strata status

Show system state.

Purpose: Displays the current health of your Strata system at a glance - how many files live in each tier, whether the daemon's awake, and where your base directory lives. It's like a dashboard, but without the JavaScript framework.

Usage:

strata status

Output includes:

  • Base directory path
  • 1st Stratum stale file count (files pending migration)
  • 2nd Stratum block count
  • 3rd Stratum shadow entry count
  • Daemon status (running/stopped, PID, cycle count)
  • Recent daemon log lines (if running)

READING / WRITING

strata add <path> <content>

Write content to the 1st Stratum.

Purpose: Create or overwrite a file in the active stratum. Works with inline text, piped input, or files from disk. The index.md regenerates automatically after each write, so you don't have to think about it.

Usage:

strata add projects/koda/requirements.md "# Koda Platform\nOAuth2 + payments"
echo "# Quick note" | strata add gtd/note.md
strata add --text "Remember to deploy the API"     # Auto-routed to gtd/
strata add --file /path/to/local/file.md projects/notes.md  # Read from file

Priority: Inline text argument > --file content > stdin. If only one positional argument is given and stdin is a pipe, content is read from stdin.

Notes:

  • Creates parent directories automatically
  • Path traversal is blocked (paths must resolve within active/)
  • Regenerates index.md after writing
  • Exit code 1 on file read failure or missing content

strata read <path>

Read a file from any stratum. Cascades active → cooled → archive.

Purpose: Print the full content of a file, no matter where it's hiding. Searches the 1st Stratum first, then falls back to the 2nd (cooled), and finally the 3rd (archive). When reading from cooled, we track access counts and automatically promote the file back to active once it hits the threshold (default: 3). When reading from archive, the file gets rehydrated to active on the spot. It's like a rescue service, but for markdown.

Usage:

strata read projects/koda/spec.md     # Active  -  fast path, no tracking
strata read user/prefs.md             # Cooled  -  auto-promotes on 3rd read
strata read archive-me.md             # Archive  -  auto-rehydrates to active

Status messages:

Output Meaning
(no message) Read from active (1st Stratum)
→ Read from cooled (access 1/3) Read from cooled; access tracked
⬆ Promoted from cooled (accessed 3 times) Reached threshold; moved to active
⬆ Restored from archive to 1st Stratum (active) Archived file rehydrated to active

Notes:

  • Exit code 1 if file is not found in any stratum or path is a directory
  • Status messages print to stdout above the file content
  • Promotion happens transparently during the read - no separate command needed

strata list [path]

List files and directories in the 1st Stratum.

Purpose: See what's in your active memory. Shows files and directories with type and size - handy when you've forgotten what you've saved.

Usage:

strata list                 # List active root
strata list projects        # List projects subdirectory

Output format: [dir] projects/ or [file] projects/koda/notes.md (1234b)

strata list-stratum-2

List 2nd Stratum (cooled) files.

Purpose: Peek at what's been migrated to the cooled tier. Shows path, size, and last modification date - the cold storage equivalent of flipping through a filing cabinet.

Usage:

strata list-stratum-2

strata index

Regenerate the 1st Stratum index.md.

Purpose: Rebuild the master map of all active files. Normally this happens automatically after every strata add, but sometimes you want to do it yourself - maybe for the satisfaction of seeing the cursor spin.

Usage:

strata index

Output: Prints the first 300 characters of the regenerated index.

SEARCHING

strata search <query>

Search across all memory tiers.

Purpose: Human-readable search across active/, cooled/, and archive/ - because you know you wrote that thing somewhere, you just don't remember where.

Usage:

strata search "koda oauth2"
strata search "postgresql pgvector"

Output format:

  [1] [ACTIVE] · score=1.50 · projects/koda/requirements.md
       # Koda Platform...OAuth2 + payments...

  [2] [ARCHIVE] · score=0.25 · archive:stratum_3_abc123.json
       # Koda Database Schema...PostgreSQL...
       [in archive -- use strata rehydrate <id> to restore]

Notes:

  • Results are ranked by relevance score
  • Tier tags: ACTIVE (stratum_1), MEDIUM (stratum_2), ARCHIVE (stratum_3)
  • Middle dot (·) separator between fields
  • Archived results show a rehydration hint
  • Exit code 1 if no query text provided

strata query <text>

Search across all memory tiers (JSON output).

Purpose: Same search as strata search, but outputs raw JSON. Perfect for when you're scripting and don't want to parse human-friendly text.

Usage:

strata query "koda oauth2"

Output: JSON array of result objects with content, tier, source, score, and metadata fields.

LIFECYCLE

strata migrate

Move stale files from active to cooled.

Purpose: Scans the 1st Stratum for files past their prime (older than their decay threshold) and moves them to the 2nd Stratum. Files stay as markdown - no magic conversion, just a change of address.

Usage:

strata migrate              # Execute migration
strata migrate --dry-run    # Preview without making changes

Notes:

  • Shows a spinner animation during execution (suppressed in piped output or JSON mode)
  • Dry run output lists files that would be migrated
  • Exit code 1 on errors

strata promote

Move hot cooled files back to active.

Purpose: Scans the 2nd Stratum for files that are getting a lot of attention and moves them back to the 1st Stratum. It's the inverse of migration - if a cooled file has been accessed 3 or more times (configurable via promotion_threshold), it gets bumped back to the working tier. Think of it as a demotion reversal.

Usage:

strata promote              # Execute promotion
strata promote --dry-run    # Preview without making changes

Notes:

  • Access count threshold is configurable via promotion_threshold in strata.json
  • Promoted files are removed from cooled/ and their access tracking is reset
  • The index is regenerated after promotion
  • Dry run shows which files would be promoted and their access counts

strata evict

Move cold files from cooled to archive.

Purpose: Scans the 2nd Stratum for files that have overstayed their welcome (exceeding LRU thresholds) and evicts them to the 3rd Stratum. Creates a JSON blob and a shadow index entry so they're not truly gone - just... hibernating.

Usage:

strata evict              # Execute eviction
strata evict --dry-run    # Preview without making changes

Notes:

  • Shows a spinner animation
  • Dry run output lists memories that would be evicted
  • Exit code 1 on errors

strata maintenance

Run full lifecycle cycle.

Purpose: Runs promote, migrate, and evict in sequence, because clicking three buttons is for people with too much time on their hands. One command, full maintenance.

Usage:

strata maintenance              # Execute all three
strata maintenance --dry-run    # Preview all

Output: JSON with promoted, migrated, and evicted arrays, plus totals.

Execution order: Promote (2nd->1st) → Migrate (1st->2nd) → Evict (2nd->3rd). This order ensures a promoted file isn't immediately re-migrated in the same cycle. The Janitor's not a fan of circular logic.

strata rehydrate <shadow_id>

Restore an archived file from the 3rd Stratum to active or cooled.

Purpose: Reverses an eviction. Takes a shadow index entry (the one you saw in strata search results) and restores the full file content to either active/ (if you want to edit it) or cooled/ (if you just need to reference it). Consider it a pardon from cold storage.

Usage:

strata rehydrate <shadow_id>
strata rehydrate <shadow_id> --target=cooled

Options:

Option Default Description
--target=active|cooled active Target tier: active (1st, editable) or cooled (2nd, query-only).

Notes:

  • The shadow ID comes from search results (the id or memory_id field in metadata)
  • Rehydrating to active/ removes the shadow index entry
  • Rehydrating to cooled/ initializes access tracking (starts at 0)
  • Exit code 1 if shadow entry not found or archive file unreadable

strata forget <path>

Archive a specific cooled file immediately.

Purpose: Explicitly archive a file from the 2nd Stratum to the 3rd Stratum. It's like an "archive now" button for a specific file - no waiting for the Janitor's next cycle.

Usage:

strata forget projects/old-idea.md

Notes:

  • File path must exist in cooled/
  • Uses the first path segment as tags
  • Exit code 1 if file not found in 2nd Stratum

strata cost

Show estimated cost savings from Janitor automation.

Purpose: Display metrics on daemon activity and estimated token savings from automated lifecycle management. Because who doesn't like seeing how much they've saved?

Usage:

strata cost

Output:

Strata Cost Savings (Estimated)
========================================
  Daemon cycles:     3
  Files migrated:    12
  Files evicted:     4
  LRU decisions:     4
  Tokens saved:      26,000 tokens
  Savings range:     20,800 - 31,200

  Methodology: Compared against hypothetical system...
  Disclaimer: These are approximate ranges...

See Tracking for detailed methodology.

DAEMON

strata serve

Start background Janitor daemon.

Purpose: Fires up a background process that runs strata maintenance on a schedule. The daemon handles lifecycle automatically - you kick back and watch your memory tiers stay tidy all on their own.

Usage:

strata serve                        # Default: 900s interval, first cycle dry run
strata serve --interval=300         # Every 5 minutes
strata serve --live                 # Skip initial dry run, go straight to live

Options:

Option Default Description
--interval=SECONDS 900 Seconds between maintenance cycles.
--live (dry run first) Skip initial dry run, execute live immediately.

Notes:

  • Checks for existing daemon PID before starting (prevents duplicates)
  • Logs to strata.log and stderr
  • PID file at strata.pid
  • Blocking - runs until interrupted (Ctrl+C)

strata daemon

Alias for strata serve.

Purpose: Some people prefer to type fewer letters. We get it.

strata stop

Stop running daemon.

Purpose: Sends SIGTERM to the running daemon and waits for it to wind down gracefully. Like asking someone nicely to stop what they're doing and finish their sentence before leaving.

Usage:

strata stop

Notes:

  • Reads PID from strata.pid
  • Waits up to 5 seconds for graceful shutdown
  • Cleans up PID file on success
  • Safe to call when daemon is not running (prints message, no error)

strata restart

Restart daemon.

Purpose: Stops the running daemon and starts a fresh one with the same (or new) arguments. A gentle "have you tried turning it off and on again?"

Usage:

strata restart
strata restart --interval=600

strata install-service

Install systemd user service for persistent daemon.

Purpose: Installs a systemd user unit that starts the Janitor daemon automatically on boot and restarts it on failure. Production deployments, this one's for you.

Usage:

strata install-service

Post-install:

systemctl --user daemon-reload
systemctl --user enable --now strata
systemctl --user status strata
journalctl --user -u strata -f

Notes:

  • Copies contrib/strata.service to ~/.config/systemd/user/strata.service
  • Uses strata serve --live as the exec command (bypasses initial dry run)
  • Service runs with security hardening: NoNewPrivileges=true, ProtectHome=read-only, ProtectSystem=strict
  • Logs to journald, not strata.log
  • Requires systemd - does not work on macOS or non-systemd Linux

strata uninstall-service

Remove systemd user service.

Purpose: Removes the previously installed systemd unit file. Cleanup is a virtue.

Usage:

strata uninstall-service

Pre-uninstall:

systemctl --user disable --now strata
strata uninstall-service
systemctl --user daemon-reload

Notes:

  • Deletes ~/.config/systemd/user/strata.service
  • Does NOT stop a running service - stop it first with systemctl --user stop strata

strata history

Show Janitor daemon log.

Purpose: Peek at what the Janitor's been up to. Useful when you want to know if it's been busy, slacking off, or silently contemplating the impermanence of all things.

Usage:

strata history              # Show last 20 lines
strata history --lines=50   # Show last 50 lines

Notes:

  • Reads from strata.log in the base directory
  • Exit code 0 even if no log exists (prints a message)

AGENT INTEGRATION

strata mcp

Start MCP protocol server.

Purpose: Starts the Model Context Protocol (MCP) server over stdio. This lets MCP-compatible agents - Claude Desktop, and friends - talk to Strata directly without going through the CLI.

Usage:

strata mcp

Notes:

  • Runs over stdio (for MCP transport)
  • Blocking - runs until stdin closes or interrupted
  • See MCP specification for protocol details

strata skill install

Install Strata skill for AI coding assistants.

Purpose: Installs the Strata agent skill, which teaches AI coding assistants about Strata's commands and architecture. Supports OpenCode, Claude Code, PI, Cursor, Codex, Windsurf, and 55+ agent formats via the Vercel Skills protocol. That's a lot of agents.

Usage:

strata skill install                 # Interactive -- choose scope + agents
strata skill install --global        # Non-interactive global install

Notes:

  • Requires Node.js (npx)
  • Interactive mode launches npx skills add with prompts
  • Global mode passes --all --global --yes flags for unattended install
  • The skill is bundled at strata/skills/strata/SKILL.md

strata pi-install

Install Strata Pi extension.

Purpose: Installs the Strata extension for the Pi coding agent. Copies strata.ts to ~/.pi/agent/extensions/ so Pi can talk to your memory tiers like it owns the place.

Usage:

strata pi-install          # Interactive (prompts before overwrite)
strata pi-install --force  # Overwrite existing extension without prompt

Notes:

  • Requires Pi CLI (pi) to be installed
  • Installs to ~/.pi/agent/extensions/strata.ts
  • After install, run /reload in Pi to activate
  • See Pi Integration for extension details

strata --agent-help

Print agent usage guide.

Purpose: Spits out inline agent help text that describes Strata architecture and commands from an AI agent's perspective. Handy when you need a refresher without leaving your terminal.

Usage:

strata --agent-help

Output: Markdown-formatted guide covering architecture, commands, best practices - designed to be injected into an agent's context so it knows what it's working with.

QMD (Optional Hybrid Search)

strata qmd-setup

Configure QMD collections for all Strata directories.

Purpose: Adds active/ and cooled/ directories as QMD collections for hybrid search. If you've got QMD installed, this wires it up.

Usage:

strata qmd-setup

Notes:

  • Collection names: strata_active, strata_cooled
  • Requires @tobilu/qmd to be installed
  • Exit code 0 even if QMD is not installed (prints a message)

strata qmd-embed

Generate vector embeddings.

Purpose: Generates vector embeddings for all QMD collections. This is what enables vector semantic search - think of it as teaching Strata to understand meaning, not just match keywords.

Usage:

strata qmd-embed

Notes:

  • May take a while on first run (especially for large collections)
  • Requires QMD to be installed
  • Exit code 0 even if QMD is not installed (prints a message)

strata qmd-status

Show QMD index status.

Purpose: Displays the health of your QMD collections and indexes. Because every good search setup deserves a checkup now and then.

Usage:

strata qmd-status

Notes:

  • Shows collection health, embedding status, index size
  • Requires QMD to be installed

Exit Codes

Code Meaning
0 Success.
1 General error (invalid args, missing data directory, file not found, daemon not running, etc.).

In JSON mode (--json / --agent), errors produce a JSON object with status: "error" and exit code 1. Consistent, parseable, and predictable - just how scripting likes it.

Cross-Reference