> ## Documentation Index
> Fetch the complete documentation index at: https://docs.crewship.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# crewship memory

> Inspect and search memory FTS5 indexes directly on the local filesystem.

# 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.

```bash theme={null}
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:**

```bash theme={null}
# 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.

```bash theme={null}
crewship memory status [flags]
```

**Example:**

```bash theme={null}
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.

```bash theme={null}
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`).

**Example:**

```bash theme={null}
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](/guides/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).

```bash theme={null}
crewship memory reindex [flags]
```

**Example:**

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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`).

## 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)                           |