crewship memory

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

Subcommands

search

FTS5 search across memory with scope control.

crewship memory search <query> [flags]

Flags:

Flag	Short	Default	Description
`--path`	`-p`	(required)	Base path (meaning depends on scope)
`--scope`	`-S`	`agent`	`agent`, `crew`, `workspace`, or `all`
`--limit`	`-l`	`10`	Maximum results per scope
`--format`	`-F`	`table`	Output 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:

Flag	Description
`--crew`	Scope to a single crew by slug or ID. Omit for workspace-aggregate.

The global --format flag is honoured (table, json, yaml, ndjson). 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

Flag	Default	Description
`--limit`	`10`	Maximum hits.
`--scope`	(all visible)	`own` (agent-only) or `crew_shared` (crew-bound).
`--crew`		Crew 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. list columns: SHA256, WRITTEN, BYTES, WRITTEN BY. --limit defaults to 20 and the server clamps it to 1–1000.

Projection state — “nothing here” vs “we could not look”

list leads with a projection state whenever it changes how the list should be read. An empty version history has two completely different meanings and they used to print the same empty table:

State	Meaning	How to read an empty list
`recorded`	A writer records this path into the audit chain.	Nothing has been written to it yet. This is a fact.
`unrecorded`	No writer records this path.	Says nothing about what is on disk — the file may have changed a hundred times.
`unavailable`	The server has no blob root configured, so no write of any tier is recorded.	Same as `unrecorded`, different cause.

Recorded paths are agent:<slug>/… or crew:<crew_id>/… ending in AGENT.md, CREW.md, pins.md, learned-*.md, or daily/*.md. Everything else — lessons.md, PERSONA.md, peers/* — is unrecorded and has its own history surface; the reason text names it. The state and its reason are printed above the table in human output and carried verbatim in --format json:

crewship memory versions list "agent:martin/lessons.md" --format json | jq .projection
# { "state": "unrecorded", "reason": "Lessons are written by consolidate.WriteLesson, ..." }

A server predating this field answers without it. The CLI reads that as recorded — the state every path had when the only writers were recording ones — so an older server is never reported as having versioning switched off.

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.

Flag	Default	Description
`--limit <n>`	`20`	Max rows. Clamped to `1000` by the local query (this command reads the DB directly, no server involved).
`--format`	`json`	`json` (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

Flag	Default	Description
`--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.
`--tier`	`learned`	Tier label for the new audit row: `agent` / `crew` / `workspace` / `pins` / `learned`.
`--force`	`false`	Skip 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).

export

Write memory out as a portable OKF bundle — markdown with YAML frontmatter, readable and git-friendly. Goes through the server, so it works from any machine the CLI can reach.

crewship memory export --crew engineering --agent alex --out ./alex-memory
crewship memory export --crew engineering --out ./crew-memory

Flag	Default	Description
`--out`	—	Destination directory for the bundle. Required.
`--crew`	—	Crew slug or id. Required.
`--agent`	—	Agent slug. Omit for the crew-shared tier.

OWNER/ADMIN only — the bundle contains every private note the agent holds. The same export is available in the dashboard: an agent’s Memory tab has an Export button that downloads the bundle. Import has no UI equivalent — see Memory Portability.

import

Read a memory directory produced by another harness, map it onto Crewship’s tiers, and write it in. Recognises crewship, okf, nanoclaw and openclaw layouts.

# Preview — no login needed, nothing written
crewship memory import --from ~/.openclaw/workspace-main --crew engineering --agent alex --operator pavel

# Write it
crewship memory import --from ./nanoclaw --group telegram_dev-team --crew eng --agent alex --apply

Flag	Default	Description
`--from`	—	Source memory directory. Required.
`--crew`	—	Target crew slug or id. Required.
`--agent`	—	Target agent slug. Omit for the crew-shared tier.
`--format`	`auto`	`auto` / `crewship` / `okf` / `nanoclaw` / `openclaw`.
`--operator`	—	Slug of the person an operator card (OpenClaw `USER.md`) belongs to. Without it the card is skipped.
`--group`	—	Which NanoClaw group to import when the source holds several. Required in that case.
`--with-crew`	`false`	Also write crew-shared documents. Every agent in the crew reads them.
`--apply`	`false`	Actually write. Without it the command prints the plan and exits.

--apply requires OWNER/ADMIN, the same as export — it writes into the context an agent reasons from. Imported documents pass through the same guards an agent’s own writes do: a closed allowlist of paths, per-file size ceilings, secret and prompt-injection scanning, and symlink-safe confinement. Refusals are listed per document and the command exits non-zero; a failed document does not stop the rest. Full mapping table and limits: Memory Portability.

Scope and Path Resolution

The meaning of --path depends on the selected scope:

Scope	`--path` should point to
`agent`	Agent `.memory/` dir or agent dir (auto-appends `.memory/`)
`crew`	Crew root dir (resolves to `<path>/shared/.memory/`)
`workspace`	Workspace memory dir (e.g. `~/.crewship/memory/<workspace-id>`)
`all`	Crew root dir (searches agent + crew)

Getting started

Sessions & identity

Agents & conversations

Crews, projects & workspaces

Missions & routines

Issues & triage

Skills & integrations

Inbox & notifications

Memory & journal

Observability

Cost & paymaster

Approvals & hooks

Configuration & system

Utilities

crewship memory

crewship memory

Subcommands

search

status

health

reindex

hybrid

versions (server API)

Projection state — “nothing here” vs “we could not look”

log

show

restore

export

import

Scope and Path Resolution

​crewship memory

​Subcommands

​search

​status

​health

​reindex

​hybrid

​versions (server API)

​Projection state — “nothing here” vs “we could not look”

​log

​show

​restore

​export

​import

​Scope and Path Resolution

crewship memory

Subcommands

search

status

health

reindex

hybrid

versions (server API)

Projection state — “nothing here” vs “we could not look”

log

show

restore

export

import

Scope and Path Resolution