Memory API: schemas

The request and response bodies of the operations in this API.

AppendEntryBodyDto

Property	Type	Required	Description
`entry`	string	yes	Markdown body of the new ledger entry. The server stamps the timestamp.
`path`	string	yes

CreateMemoryBodyDto

Property	Type	Required	Description
`fileText`	string	yes	Full markdown body for the new memory file.
`path`	string	yes

MaintenanceProposalResponseDto

Property	Type	Required
`appliedAt`	object or null	no
`createdAt`	string	yes
`id`	string (uuid)	yes
`kind`	one of `"MERGE"`, `"PRUNE"`, `"RENAME"`, `"SUMMARY_REFRESH"`, `"FLAG_EMPTY_ORPHAN"`	yes
`payload`	object	yes
`reason`	object or null	no
`runId`	string (uuid)	yes
`status`	one of `"PROPOSED"`, `"APPLIED"`, `"SKIPPED_DIGEST_GATE"`, `"SKIPPED_HASH_MISMATCH"`, `"FAILED"`, `"REVERTED"`	yes

MaintenanceProposalResponseDtoDataEnvelope

Property	Type	Required	Description
`data`	MaintenanceProposalResponseDto	yes

MaintenanceRunDetailDto

Property	Type	Required	Description
`completedAt`	object or null	no
`id`	string (uuid)	yes
`mode`	one of `"DRY_RUN"`, `"APPLY"`	yes
`orgId`	string (uuid)	yes
`proposals`	array of MaintenanceProposalResponseDto	yes
`serviceActor`	string	yes
`startedAt`	string	yes
`status`	one of `"RUNNING"`, `"SUCCEEDED"`, `"FAILED"`	yes
`totals`	map of number or null	no	Aggregated counters once the run completes. `{ merged, pruned, renamed, summariesRefreshed, flagged, skippedDigestGate, skippedHashMismatch }`.

MaintenanceRunDetailDtoDataEnvelope

Property	Type	Required	Description
`data`	MaintenanceRunDetailDto	yes

MaintenanceRunResponseDto

Property	Type	Required	Description
`completedAt`	object or null	no
`id`	string (uuid)	yes
`mode`	one of `"DRY_RUN"`, `"APPLY"`	yes
`orgId`	string (uuid)	yes
`serviceActor`	string	yes
`startedAt`	string	yes
`status`	one of `"RUNNING"`, `"SUCCEEDED"`, `"FAILED"`	yes
`totals`	map of number or null	no	Aggregated counters once the run completes. `{ merged, pruned, renamed, summariesRefreshed, flagged, skippedDigestGate, skippedHashMismatch }`.

MaintenanceRunResponseDtoDataArrayEnvelope

Property	Type	Required	Description
`data`	array of MaintenanceRunResponseDto	yes

MemoryDetailDto

Property	Type	Required	Description
`content`	string	yes	Full markdown body, including YAML frontmatter and ledger entries.
`createdAt`	string (date-time)	yes
`createdByAgent`	string	yes
`createdBySurface`	MemorySurface	yes
`id`	string (uuid)	yes
`kind`	MemoryKind	yes
`ownerSpaceUri`	string	yes	Canonical owner Space URI, e.g. `xema://orgs/<orgId>`.
`path`	string	yes	Canonical path, e.g. `/memories/project/lesson/foo.md`.
`projectSlug`	string	no	Project slug when the owner Space is a project. The list endpoint surfaces this so the UI can render cross-project read results next to the canonical path.
`slug`	string	yes
`summary`	string	yes	≤1024-char auto-generated abstract.
`summaryModel`	string	no	Model slug that produced the current summary (Model Resolution Matrix decision).
`summaryUpdatedAt`	string (date-time)	no
`tags`	array of string	yes
`updatedAt`	string (date-time)	yes

MemoryDetailDtoDataEnvelope

Property	Type	Required	Description
`data`	MemoryDetailDto	yes

MemoryKind

Type: one of "LESSON", "PATTERN", "CORRECTION", "PREFERENCE"

MemoryListResponseDto

Property	Type	Required	Description
`memories`	array of MemorySummaryDto	yes
`visibleScopes`	array of string	yes	Owner-tier segments visible to the caller.

MemoryListResponseDtoDataEnvelope

Property	Type	Required	Description
`data`	MemoryListResponseDto	yes

MemoryProjectDto

Property	Type	Required
`name`	string	yes
`projectId`	string (uuid)	yes
`role`	string	yes
`slug`	string	yes

MemoryProjectListResponseDto

Property	Type	Required	Description
`projects`	array of MemoryProjectDto	yes

MemoryProjectListResponseDtoDataEnvelope

Property	Type	Required	Description
`data`	MemoryProjectListResponseDto	yes

MemorySearchDegradedReason

Why vector search was not used, or null when it was. embedding_provider_unavailable is transient and recovers on its own; embedding_not_configured is permanent until an org admin picks an embedding model, so a "try again" banner is the wrong response to it.

Type: one of "embedding_not_configured", "embedding_provider_unavailable"

MemorySearchResponseDto

Property	Type	Required	Description
`degraded`	boolean	yes	True when the response was produced by the keyword-similarity fallback rather than by vector search. Read `degradedReason` to decide what to tell the user — the two causes need opposite messages.
`degradedReason`	MemorySearchDegradedReason or null	yes	Why vector search was not used, or null when it was. `embedding_provider_unavailable` is transient and recovers on its own; `embedding_not_configured` is permanent until an org admin picks an embedding model, so a "try again" banner is the wrong response to it.
`memories`	array of MemorySummaryDto	yes
`query`	string	yes	Echoed search query.
`visibleScopes`	array of string	yes	Owner-tier segments visible to the caller.

MemorySearchResponseDtoDataEnvelope

Property	Type	Required	Description
`data`	MemorySearchResponseDto	yes

MemorySummaryDto

Property	Type	Required	Description
`createdByAgent`	string	yes
`createdBySurface`	MemorySurface	yes
`id`	string (uuid)	yes
`kind`	MemoryKind	yes
`ownerSpaceUri`	string	yes	Canonical owner Space URI, e.g. `xema://orgs/<orgId>`.
`path`	string	yes	Canonical path, e.g. `/memories/project/lesson/foo.md`.
`projectSlug`	string	no	Project slug when the owner Space is a project. The list endpoint surfaces this so the UI can render cross-project read results next to the canonical path.
`slug`	string	yes
`summary`	string	yes	≤1024-char auto-generated abstract.
`tags`	array of string	yes
`updatedAt`	string (date-time)	yes

MemorySummaryDtoDataEnvelope

Property	Type	Required	Description
`data`	MemorySummaryDto	yes

MemorySurface

Type: one of "AGENT_SESSION", "WORKFLOW"

OrgAdminStartRunBodyDto

Property	Type	Required	Description
`mode`	one of `"DRY_RUN"`, `"APPLY"`	yes	`DRY_RUN` produces proposals without applying; `APPLY` mutates state through the writer.

RenameMemoryBodyDto

Property	Type	Required	Description
`newPath`	string	yes
`oldPath`	string	yes

StartMaintenanceRunResponseDto

Property	Type	Required	Description
`partitions`	array of string	yes	Pre-resolved candidate lists per `(ownerSpaceKind, kind)` partition. Already digest-gated — every entry needs LLM judgement (or, for SUMMARY_REFRESH, an actual summarize call).
`run`	MaintenanceRunResponseDto	yes

StartMaintenanceRunResponseDtoDataEnvelope

Property	Type	Required	Description
`data`	StartMaintenanceRunResponseDto	yes

StrReplaceBodyDto

Property	Type	Required
`newStr`	string	yes
`oldStr`	string	yes
`path`	string	yes