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/agents/{agentId}/memory`	Current agent and shared knowledge
GET	`/api/v1/crews/{crewId}/memory`	Current crew and workspace knowledge
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
POST	`/api/v1/memory/initialize`	Initialize missing administrative 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.

Current knowledge inventory

`GET /api/v1/agents/{agentId}/memory`

Reads the agent’s current knowledge and its crew’s shared knowledge. It does not start or provision a container. Requires an authenticated workspace member; agentId must belong to the workspace resolved from the session and workspace_id query parameter or X-Workspace-ID header. No request body. Both routes also include workspace knowledge when its storage root is configured. The CLI for both is crewship memory inventory --agent|--crew. Personal users/ and peers/ files are excluded: read your preferences through the /api/v1/users/me/user-model and /api/v1/users/me/peer-cards endpoints. Persona is edited through the agent or crew persona API.

Response field	Type	Meaning
`source`	string	`current_files`; these are current files, not historical snapshots.
`scopes`	object	Each included scope (`agent`, `crew`, `workspace`) is `available`, `empty`, or `unavailable`.
`documents`	array	Current knowledge documents from readable scopes.
`documents[].id`	string	Scope plus relative note name; selection identity within this inventory.
`documents[].name`, `scope`	string	Relative note name and owning scope.
`documents[].state`	string	`available` or `unavailable`; an unreadable file is not empty content.
`documents[].content`	string, optional	Current content; omitted for unreadable or empty notes.
`documents[].bytes`	integer or null	Readable content length, otherwise unknown.
`documents[].revision`	string, optional	SHA-256 of the current readable content.
`documents[].updated_at`	string, optional	Current file modification time in UTC.
`documents[].history_path`	string, optional	Separate version-history key; crew paths use immutable crew IDs.
`peer_generation`	string	`unavailable` while automatic agent-specific profiles are not generated.

Response status codes for both routes:

Status	Meaning
`200`	Inventory returned, possibly with individual unavailable scopes/documents.
`401`	Authentication or workspace context is missing.
`403`	Workspace access is refused by authorization middleware.
`404`	The selected agent/crew does not exist in this workspace.
`503`	Entity lookup or required memory storage is unavailable.

Reads are bounded to 64 KiB per document and 512 KiB per scope. Directory inventories above the supported bound are unavailable rather than partial counts. Symlinks are excluded. Responses use Cache-Control: private, no-store. History may be unavailable even when current content is readable.

`GET /api/v1/crews/{crewId}/memory`

Reads the crew’s shared knowledge. Requires an authenticated workspace member; crewId must belong to that workspace. The workspace selection and response contract are the same as the agent inventory. No request body. Response: 200 JSON with source, scopes, documents and peer_generation, using the inventory fields documented above. There is no agent scope on this route. Example for a new crew:

{"source":"current_files","scopes":{"crew":"empty","workspace":"unavailable"},"documents":[],"peer_generation":"unavailable"}

Status	Meaning
`200`	Current inventory returned, including per-scope availability.
`401`	Authentication or workspace context is missing.
`403`	Workspace access refused.
`404`	Crew does not exist in the current workspace.
`503`	Entity lookup or required storage is unavailable.

General member version-history routes reject personal users/ and peers/ paths with 403; use the self-service privacy APIs. Explicit administrator compliance routes retain their separate authorization.

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.

`POST /api/v1/memory/initialize`

Auth: OWNER or ADMIN in the target workspace. Used by crewship seed --server <url> --with-memory; all files belong to the server’s storage root. Request: application/json, capped at 128 KiB:

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

crew_id identifies a crew in the authenticated workspace. Optional agent_slug selects an agent in that crew. documents contains 1–8 entries, each with path and a non-empty body. Crew scope accepts CREW.md (4 KiB) and learned.md (8 KiB). Agent scope accepts AGENT.md (4 KiB), PERSONA.md (1536 bytes), pins.md (8 KiB), and daily/YYYY-MM-DD.md (32 KiB). Every document is validated before writes begin. Each missing file is published durably without replacing an existing file; retries preserve operator edits. Symlink parents and leaves are refused. The batch is not transactional: a storage failure can leave earlier documents initialized; retrying safely completes the missing documents. Fresh installation seeding initializes memory before container provisioning takes ownership of its tree. This endpoint is for host-writable bootstrap storage. A missing document in an already provisioned tree owned by the runtime user can return 409; it does not change ownership or permissions. Use the ordinary memory import API for live runtime edits. Response: 200 OK, with counts covering every requested document:

{"written":1,"existing":0}

Status	Condition
`200`	All documents were initialized or already existed as regular files.
`400`	Invalid or oversized JSON, document count, path, duplicate, or body.
`401`	Missing authenticated workspace context.
`403`	Caller is not OWNER or ADMIN.
`404`	Crew or agent is outside the authenticated scope.
`409`	Unsafe path, permissions, or durable storage publication failure. Existing files are preserved.
`422`	Prompt injection or credential content rejected.
`500`	Scope lookup failed.
`503`	Server storage base path is not configured.

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

​Current knowledge inventory

​GET /api/v1/agents/{agentId}/memory

​GET /api/v1/crews/{crewId}/memory

​Memory portability

​GET /api/v1/memory/export

​POST /api/v1/memory/import

​POST /api/v1/memory/initialize

​Health

​Get health snapshot

​Hybrid search

​Memory versions audit trail

​GET /api/v1/memory/versions

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

​Tenancy

​Related

Endpoints

Current knowledge inventory

`GET /api/v1/agents/{agentId}/memory`

`GET /api/v1/crews/{crewId}/memory`

Memory portability

`GET /api/v1/memory/export`

`POST /api/v1/memory/import`

`POST /api/v1/memory/initialize`

Health

Get health snapshot

Hybrid search

Memory versions audit trail

`GET /api/v1/memory/versions`

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

Tenancy

Related