Memory - Crewship

The Memory API exposes the read surfaces over an agent’s episodic and markdown memory: a health snapshot that scores how usable the memory is, a hybrid recall search that fuses two retrieval engines, and the version audit trail for canonical memory files. The mutating restore endpoint lives on the Admin reference because it requires OWNER/ADMIN.

Every endpoint requires authentication and workspace context. workspace_id is accepted only by the workspace middleware (query parameter, path context, or X-Workspace-ID); it is never part of a memory operation’s payload. crew_id, when set, is validated against the caller’s workspace (cross-tenant lookups return 404).

Endpoints

Method	Endpoint	Purpose
GET	`/api/v1/memory/health`	Memory health snapshot (five metrics + composite)
POST	`/api/v1/memory/search/hybrid`	Fused FTS5 + episodic memory recall
GET	`/api/v1/memory/versions`	Audit chain for one canonical memory path
GET	`/api/v1/memory/versions/{sha}`	Raw blob bytes for one historical version
GET	`/api/v1/memory/export`	Export mapped memory documents or an OKF ZIP
POST	`/api/v1/memory/import`	Import mapped memory documents

Export and import require OWNER or ADMIN (the route’s manage role). The workspace is selected by the authenticated session’s workspace context; workspace_id is not part of either operation’s request payload. Both require crew_id; an empty agent_slug addresses crew-shared memory.

Memory portability

`GET /api/v1/memory/export`

Request: no body. Required query parameter crew_id identifies a crew in the caller’s workspace; optional agent_slug selects an agent within that crew. With no format (or any value other than zip), the response is 200 OK, application/json:

{
  "format": "crewship",
  "documents": [{"path": "AGENT.md", "tier": "agent", "body": "# Notes\n"}],
  "skipped": [{"source": "links/other.md", "reason": "symlink"}]
}

documents and skipped are always arrays. Document fields are path, tier, and body, with scope, title, tags, and sources omitted when empty. Each skipped entry has source and reason. With format=zip, a non-empty scope returns 200 OK with Content-Type: application/zip, Content-Disposition: attachment, and a Content-Length; the body is the OKF ZIP bundle, not JSON.

Status	Condition
`200`	JSON export, or a non-empty ZIP export.
`400`	Missing `crew_id`.
`401`	No authenticated workspace context.
`404`	Crew/agent is not in the caller’s workspace, or `format=zip` selects an empty scope.
`500`	Database, memory-tree, or bundle construction failure.
`503`	Storage base path is not configured.

`POST /api/v1/memory/import`

Request: application/json, capped at 32 MiB:

{"crew_id":"crew_123","agent_slug":"alex","documents":[{"path":"AGENT.md","tier":"agent","body":"# Notes\n"}]}

crew_id, agent_slug, and documents are request fields; every document requires path, tier, and body. The operation is per-document rather than transactional. 200 OK returns:

{
  "written": ["AGENT.md"],
  "rejected": [{"path": "secrets.md", "kind": "secret", "detail": "..."}],
  "failed": [{"path": "daily/today.md", "reason": "write failed"}]
}

detail is omitted when empty; a successful response can contain rejected or failed documents. Prompt-injection findings are reported in rejected with kind: "prompt_injection".

Status	Condition
`200`	Request processed; inspect `written`, `rejected`, and `failed`.
`400`	Invalid JSON, no documents, invalid target, or unknown tier.
`401`	No authenticated workspace context.
`404`	Crew or agent is not in the caller’s workspace.
`413`	Request exceeds 32 MiB.
`500`	Database, write-policy, or memory-tree failure.

Health

Read-only snapshot for the memory health dashboard. Backed by internal/consolidate.ComputeHealth. The five aggregate queries it runs are cheap, so the handler recomputes on every request rather than reading the persisted memory_health_snapshots table — those snapshots exist for time-series plots, not real-time reads. See Episodic memory — health scoring for the formula and operator interpretation.

Get health snapshot

GET /api/v1/memory/health

Query parameters:

Param	Type	Description
`crew_id`	string	Optional. Crew ID (not slug) to scope the score to a single crew. Omit for workspace-aggregate. The ID is validated against the caller’s workspace via `crewBelongsToWorkspace`; a foreign ID returns `404`.

Auth: Every workspace member can read. The response contains only counts and ratios, no raw entry content. Response: 200 OK

{
  "workspace_id": "ws_123",
  "crew_id": "",
  "computed_at": "2026-04-30T11:42:18.018Z",
  "overall": 77.4,
  "metrics": {
    "freshness":    83.1,
    "coverage":     62.0,
    "coherence":    80.2,
    "efficiency":   77.4,
    "reachability": 78.0
  },
  "details": {
    "freshness_recent_24h":     12,
    "freshness_baseline_daily":  9.4,
    "coverage_distinct_types":   5,
    "coherence_relations":       1284,
    "coherence_embeddings":      1390,
    "efficiency_archived":       640,
    "efficiency_live":           1390,
    "reachability_connected":    1084
  }
}

Field	Type	Description
`workspace_id`	string	Echo of the session’s workspace.
`crew_id`	string	Echo of the request’s `crew_id` (empty for workspace-aggregate).
`computed_at`	string (RFC3339)	When this response was computed. The handler always recomputes, so this is `now`.
`overall`	number	Weighted composite, 0–100. Formula: `0.25·freshness + 0.25·coverage + 0.20·coherence + 0.15·efficiency + 0.15·reachability`.
`metrics.*`	number	Each metric, 0–100. See the guide for what each one measures.
`details`	object	Free-form supplementary data — the per-metric inputs each score was derived from (`freshness_recent_24h`, `coverage_distinct_types`, `coherence_relations`/`coherence_embeddings`, `efficiency_archived`/`efficiency_live`, `reachability_connected`, …). Schema is not stable across versions; consume defensively.

There is no separate band field — clients categorise locally:

Band	Range
Red	`overall < 50`
Yellow	`50 ≤ overall < 75`
Green	`overall ≥ 75`

The CLI uses these exact thresholds (internal/cli colour helpers) and the FE follows. Errors:

Status	Condition
401	No workspace context in session.
404	`crew_id` set and not in caller’s workspace.
500	Compute failure — propagated from `ComputeHealth`.

Hybrid search

POST /api/v1/memory/search/hybrid

Single-shot memory recall that fuses two retrieval engines and merges their results with Reciprocal Rank Fusion (RRF, k = 60):

FTS5 / BM25 — the workspace-tier full-text index over markdown memory.
Episodic recall — dense-vector + BM25 recall over the crew journal.

The handler degrades gracefully: if only one engine is wired (no embedder, or no FTS engine for the workspace), it returns that engine’s results alone; if neither has matches it returns 200 with an empty hits array and count: 0 — the same shape the sidecar /memory/search uses. Auth: required + workspace context (MEMBER+). Every query is anchored on the caller’s session workspace, so a foreign workspace_id cannot be smuggled through the body. Request body:

{
  "query": "deploy script flakiness",
  "limit": 10,
  "scope": "crew_shared",
  "crew_id": "crew_123"
}

Field	Type	Default	Description
`query`	string	—	Required. The search text. `400` when empty.
`limit`	integer	`10`	Max hits to return. Non-positive values fall back to the default; capped at `50` server-side.
`scope`	string	`""`	One of `""` (no scope filter, MEMBER+ implied), `"own"` (caller’s own memory only), or `"crew_shared"` (crew-shared memory). Any other value is `400`.
`crew_id`	string	—	Binds `crew_shared` results to a single crew. Required when `scope` is `crew_shared` (`400` if omitted), and the caller must be a member of that crew in this workspace (`403` otherwise). Ignored for other scopes.

Response: 200 OK

{
  "query": "deploy script flakiness",
  "count": 2,
  "hits": [
    {
      "source": "fts",
      "score": 0.0163,
      "fts": { "...": "FTS5 chunk hit" }
    },
    {
      "source": "episodic",
      "score": 0.0159,
      "episodic": { "...": "journal entry hit" }
    }
  ]
}

The unused half of each hit is omitted, not emitted as null (fts / episodic both carry omitempty): an FTS-sourced hit has no episodic key and vice-versa.

Field	Type	Description
`query`	string	Echo of the request’s `query`.
`count`	integer	`len(hits)`.
`hits[]`	array	Fused, RRF-ranked results.
`hits[].source`	string	`"fts"` or `"episodic"` — which engine produced the hit.
`hits[].score`	number	The RRF score used for ranking (higher = better).
`hits[].fts`	object?	The FTS5 chunk payload; omitted on episodic-sourced hits.
`hits[].episodic`	object?	The episodic journal-entry payload; omitted on FTS-sourced hits.

Status	Condition
`400`	Malformed JSON, empty `query`, an invalid `scope`, or `scope=crew_shared` without a `crew_id`.
`401`	No workspace context in the session.
`403`	`scope=crew_shared` for a crew the caller is not a member of (or that is not in this workspace).
`500`	Underlying `memory.HybridSearch` failed.

Memory versions audit trail

The HTTP mirror of crewship memory log/show. Workspace is anchored from the session — query strings never carry workspace_id, so a cross-workspace probe can’t smuggle a foreign id through. Restore (POST /api/v1/memory/versions/{sha}/restore) is documented separately on the Admin reference because it requires OWNER/ADMIN and mutates canonical state; the two read endpoints below are MEMBER+.

`GET /api/v1/memory/versions`

Returns the audit chain for one canonical memory path, newest-first. Auth: required + workspace context. Query parameters:

Param	Type	Default	Description
`path`	string	—	Required. Canonical memory path (e.g. `agent:martin/AGENT.md`). 400 when omitted.
`limit`	integer	`50`	Max rows to return. Applies only when the query string is present: a positive value is clamped to a hard ceiling of `500`; a non-positive or non-numeric value returns `400`. Omitting `limit` uses the default.

Response: 200 OK

{
  "path": "agent:martin/AGENT.md",
  "count": 2,
  "entries": [
    {
      "id": "mv_01HZA...",
      "path": "agent:martin/AGENT.md",
      "tier": "agent",
      "sha256": "abc...",
      "bytes": 1284,
      "written_at": "2026-05-18T08:30:00Z",
      "written_by": "audit-watcher",
      "parent_sha": "def...",
      "payload_ref": "/var/lib/crewship/memory/versions/ab/abc..."
    },
    {
      "id": "mv_01HZ9...",
      "path": "agent:martin/AGENT.md",
      "tier": "agent",
      "sha256": "def...",
      "bytes": 1180,
      "written_at": "2026-05-17T22:11:48Z",
      "written_by": "audit-watcher",
      "payload_ref": "/var/lib/crewship/memory/versions/de/def..."
    }
  ],
  "projection": {
    "state": "recorded",
    "reason": "Recorded by the memory audit watcher on every write, and by the consolidator for the files it maintains."
  }
}

Field	Type	Description
`path`	string	Echo of the request’s `path`.
`count`	integer	`len(entries)` — handy when paging is bounded by `limit`.
`entries[]`	array	Newest-first list of `memory_versions` rows for this path in the caller’s workspace.
`projection.state`	string	`recorded`, `unrecorded`, or `unavailable` — see below.
`projection.reason`	string	Human-readable explanation, safe to render to an operator verbatim.
`entries[].tier`	string	`agent`, `crew`, `workspace`, `pins`, or `learned`.
`entries[].parent_sha`	string?	sha256 of the prior version in the chain. Omitted (not `null`) on the root version — the field carries `omitempty` and the column is COALESCE’d to `""`.
`entries[].payload_ref`	string	On-disk path to the content-addressed blob.

Status	Condition
`400`	Missing `path` query parameter, or a `limit` that is non-positive / non-numeric.
`401`	No workspace context in the session.
`500`	Underlying `memory.LogVersions` query failed.

projection — whether an empty entries may be read as a fact. memory_versions is a projection of the .memory tree, not the tree itself: a file appears only if some writer records it. An unprojected path and a path nobody has written to both answer {"entries": []}, and a client cannot tell them apart — so the server says which it is. Clients must not hard-code the list of projected tiers; it is a property of the writers and it changes.

`state`	Means	How a UI should render an empty list
`recorded`	Some writer records this path.	”Nothing has been written yet” — a fact.
`unrecorded`	No writer records this path (e.g. `lessons.md`, `PERSONA.md`, peer cards).	”This cannot be read here”, plus `reason`. Never as an empty history.
`unavailable`	Versioning is off on this server (no blob root), so no path of any tier is recorded.	”The trail is not being collected”, plus `reason`.

`GET /api/v1/memory/versions/{sha}`

Returns the raw blob bytes for one historical version. Pipe-friendly: the body is the historical content, metadata travels in headers so a CLI pipe to a file produces the exact bytes that were written. Auth: required + workspace context. Path parameters:

Param	Description
`sha`	Content sha256 from `memory_versions.sha256`.

Query parameters:

Param	Type	Description
`path`	string	Required. The canonical memory path the sha was written under. The same sha can be paired with different paths if two paths happen to converge on identical content.

Response: 200 OK — raw bytes, Content-Type: application/octet-stream.

Header	Description
`X-Memory-Version-Sha`	Echo of the path’s sha.
`X-Memory-Version-Bytes`	Body length (matches `memory_versions.bytes`).

Status	Condition
`400`	Missing `sha` path segment or missing `path` query parameter.
`401`	No workspace context.
`404`	No `memory_versions` row matches `(workspace_id, path, sha)` — cross-workspace lookups masked as 404 to avoid leaking row existence.
`500`	Read failure from the underlying blob store.

The restore endpoint (POST /api/v1/memory/versions/{sha}/restore) is OWNER/ADMIN-only and applies extra server-side path confinement to refuse canonical targets outside the configured memory root. See the Admin reference for the full mutation surface.

Tenancy

workspace_id is always pulled from the session — never accepted as a query parameter or body field.
crew_id, when set, is validated via crewBelongsToWorkspace (same helper as the Paymaster API). Cross-tenant lookups return 404.

Episodic memory guide.
crewship memory health — CLI wrapper.
Crew Journal — source of indexed entries.

​Endpoints

​Memory portability

​GET /api/v1/memory/export

​POST /api/v1/memory/import

​Health

​Get health snapshot

​Hybrid search

​Memory versions audit trail

​GET /api/v1/memory/versions

​GET /api/v1/memory/versions/{sha}

​Tenancy

​Related

Endpoints

Memory portability

`GET /api/v1/memory/export`

`POST /api/v1/memory/import`

Health

Get health snapshot

Hybrid search

Memory versions audit trail

`GET /api/v1/memory/versions`

`GET /api/v1/memory/versions/{sha}`

Tenancy

Related