Skip to main content

​
crewship memory

Access memory FTS5 indexes on the local filesystem without a running server. Useful for development, debugging, and scripting.

​
Subcommands

FTS5 search across memory with scope control. 
crewship memory search <query> [flags]
Flags:
FlagShortDefaultDescription
--path-p(required)Base path (meaning depends on scope)
--scope-Sagentagent, crew, workspace, or all
--limit-l10Maximum results per scope
--format-FtableOutput format: table or json
Examples: 
# Search agent memory
crewship memory search "PostgreSQL" -p /path/to/agents/lead/.memory

# Search crew shared memory
crewship memory search "deployment" -p /path/to/crew-root -S crew

# Search both scopes, JSON output
crewship memory search "database" -p /path/to/agents/lead -S all -F json

# Search workspace memory
crewship memory search "budget" -p ~/.crewship/memory/ws-123 -S workspace

​
status

Show memory index statistics. 
crewship memory status [flags]
Example: 
crewship memory status -p /path/to/agents/lead/.memory
# [agent] /path/to/agents/lead/.memory
#   Files:   3
#   Chunks:  12
#   Size:    48 KB
#   Indexed: 2026-04-14T10:15:52Z
#   Ready:   true

​
health

Print the 5-metric memory health score for the caller’s workspace. Hits the running server (requires crewship login and a workspace context) — unlike search/status/reindex which read local FTS indexes, health calls GET /api/v1/memory/health, which recomputes fresh on every request from five aggregate SQL queries. The persisted memory_health_snapshots table is for trend graphs, not for this command. 
crewship memory health [--crew <slug-or-id>]
Flags:
FlagDescription
--crewScope to a single crew by slug or ID. Omit for workspace-aggregate.
The global --format flag is honoured (table, json, yaml). Example: 
crewship memory health
# Memory health (workspace-wide): 77/100
#
#   freshness        83.1
#   coverage         62.0
#   coherence        80.2
#   efficiency       77.4
#   reachability     78.0
The 77/100 is colour-coded — red below 50, yellow 50–74, green 75 and above. The colour is applied via terminal escape codes; in pipes (| cat or --format json) it disappears. See Episodic memory — health scoring for what each metric measures and the weighted-composite formula.

​
reindex

Rebuild FTS5 index from markdown files. Signal-aware (responds to SIGINT/SIGTERM). 
crewship memory reindex [flags]
Example: 
crewship memory reindex -p /path/to/crew-root -S crew
# [crew] reindexed 3 files (10 chunks) in 19ms
Returns non-zero exit code if all reindex operations fail.

​
hybrid

Search workspace memory through the server’s hybrid engine — full-text chunks plus episodic journal recall, merged and ranked. Unlike search (local filesystem FTS), this requires a login token and works from any machine. 
crewship memory hybrid "deploy runbook"
crewship memory hybrid "API key rotation" --limit 5 --scope crew_shared --crew backend
FlagDefaultDescription
--limit10Maximum hits.
--scope(all visible)own (agent-only) or crew_shared (crew-bound).
--crewCrew slug or id for crew_shared scope.

​
versions (server API)

The memory versions group mirrors log/show/restore over the running server’s API — use these from any machine; the direct-DB commands below only work on the server host. The workspace comes from the auth context. 
crewship memory versions list "crew:<crew_id>/learned-x.md" --limit 20
crewship memory versions show "crew:<crew_id>/learned-x.md" <sha> > recovered.md
crewship memory versions restore "crew:<crew_id>/learned-x.md" <sha> <canonical-path> --tier learned
restore requires OWNER/ADMIN, prompts for confirmation (--yes skips), and the server confines <canonical-path> to its configured memory root.

​
log

List the memory_versions audit chain for a path, newest-first. Reads the local DB directly (openAdminDB — same DB the server uses) rather than going through the API; that means it works without a running server but the binary must run on the same host as the data dir. 
crewship memory log <workspace-id> <path>
crewship memory log <workspace-id> <path> --limit 100 --format text
<path> is the audit-trail identifier the consolidator + approve flow record under. For canonical learned files this is crew:<crew_id>/learned-YYYY-MM-DD.md (see internal/consolidate.canonicalAuditPath); for pins it’s crew:<crew_id>/pins.md.
FlagDefaultDescription
--limit <n>20Max rows. Clamped to 1000 by the local query (this command reads the DB directly, no server involved).
--formatjsonjson (pretty-printed) or text (one row per line, git-log–style: <sha-12> <ts> <bytes> B <writtenBy>).
Empty result prints no versions for <ws> @ <path> to stderr and exits 0.

​
show

Print the raw content of one historical version to stdout. The canonical file on disk is not touched — this is the “preview without restoring” path. 
crewship memory show <workspace-id> <path> <sha>
crewship memory show <ws> <path> <sha> > preview.md
Stdout = raw blob bytes (pipe-friendly). Stderr carries status/errors. Exit codes:
  • 0 — blob found and streamed
  • 1 — version not found or read error
  • 2 — invalid usage

​
restore

Atomically replace the canonical memory file at <canonical-path> with the content of version <sha>, then write a fresh memory_versions row so the chain stays forward-only — history is never rewritten. 
crewship memory restore <workspace-id> <path> <sha> <canonical-path>
crewship memory restore ws_a crew:abc/learned-2026-05-20.md <sha> /data/memory/ws_a/crew_abc/learned-2026-05-20.md \
  --user operator@example.com --tier learned
FlagDefaultDescription
--blob-root{CREWSHIP_DATA_DIR}/memory/versions (or ~/.crewship/memory/versions)Content-addressed blob store root. Match what the server wrote to.
--user$USER (falls back to cli)writtenBy for the new audit row. Use a real operator id for compliance trails.
--tierlearnedTier label for the new audit row: agent / crew / workspace / pins / learned.
--forcefalseSkip the “canonical path must stay inside the data dir” guard. Use only when a workspace’s memory dir lives outside the standard tree.
The path guard rejects empty strings, any path containing .., and any target whose absolute form does not start with {blob-root}/.. (the data dir, one level above versions).

​
Scope and Path Resolution

The meaning of --path depends on the selected scope:
Scope--path should point to
agentAgent .memory/ dir or agent dir (auto-appends .memory/)
crewCrew root dir (resolves to <path>/shared/.memory/)
workspaceWorkspace memory dir (e.g. ~/.crewship/memory/<workspace-id>)
allCrew root dir (searches agent + crew)