Skip to content

Memory ORM Contract

Plan Metadata

  • Plan type: plan
  • Parent plan: N/A
  • Depends on: N/A
  • Status: documentation

System Intent

  • What is being built: A source-of-truth contract for the memory ORM record shape and the ORM methods that create and mutate memory persistence state for upload and ingest flows.
  • Primary consumer(s): memory-upload-flow.md, ingest-memory.md, and server-side ORM callers in upload and ingest lambdas.
  • Boundary (black-box scope only): Record type definition plus method-level create/update contracts. Out of scope: Lambda transport details, S3 MPU behavior, and embedding model internals.

Stage Gate Tracker

  • [x] Stage 1 type definition boundary approved
  • [x] Stage 2 I/O contracts approved
  • [x] Stage 3 pseudocode/technical details approved or skipped

1. Type Definition Boundary (Diagram Substitute)

User-requested format: this plan uses a type-definition boundary instead of a Mermaid diagram.

MemoryOrm {
  memory_id: string (primary record id)
  user_id: string (owner identity)
  expected_upload_count: number (count of MPU uploads declared at start)
  completed_upload_count: number (count of MPU uploads successfully completed)
  failed_upload_count: number (count of MPU uploads that reached terminal failed state)
  text?: string[] (optional convenience projection for text asset keys)
  photos?: string[] (optional convenience projection for photo asset keys)
  audio?: string[] (optional convenience projection for audio asset keys)
  video?: string[] (optional convenience projection for video asset keys)
  memory_upload_status: "started" | "in_progress" | "uploaded" | "failed" | "aborted" | "processed"
  embedding_vector: vector[384] | null (written by post-upload ingest flow)
}

2. Black-Box Inputs and Outputs

Global Types

MemoryStatusValue {
  value: "started" | "in_progress" | "uploaded" | "failed" | "aborted" | "processed"
}

MemoryUploadProgressCounts {
  expected_upload_count: number
  completed_upload_count: number
  failed_upload_count: number
}

MemoryEmbeddingVector {
  value: number[384] (vector length must equal 384)
}

StandardError {
  status: number (HTTP or equivalent status)
  message: string (human-readable summary)
}

Flow: createMemory

  • Test files: main/server/tests/unit/test_memory_orm.py
  • Core files: main/server/layers/shared/python/shared/orm/memory_orm.py

Type Definitions

CreateMemoryInput {
  user_id: string (required)
  memory_type: string (required)
  raw_memory: string (required)
  memory_upload_id: string (required)
  expected_upload_count?: number (optional; defaults to 1)
}

CreateMemoryOutput {
  value: string (memory_id)
}

Paths

path-name input output/expected state change path-type notes updated
createMemory.success CreateMemoryInput CreateMemoryOutput; MemoryOrm row is created for memory_id with embedding_vector=null happy path record creation contract used by upload start flow
createMemory.invalid-input CreateMemoryInput StandardError status=500 message=Missing user_id, memory_type, raw_memory, or memory_upload_id OR Invalid expected_upload_count error missing required fields fail before persistence

Flow: updateMemoryStatus

  • Test files: main/server/tests/unit/test_memory_orm.py
  • Core files: main/server/layers/shared/python/shared/orm/memory_orm.py

Type Definitions

UpdateMemoryStatusInput {
  memory_id: string (required)
  status: MemoryStatusValue (required)
}

UpdateMemoryStatusOutput {
  value: void (side-effect only; updates persisted status)
}

Paths

path-name input output/expected state change path-type notes updated
updateMemoryStatus.success UpdateMemoryStatusInput UpdateMemoryStatusOutput; MemoryOrm.memory_upload_status is updated happy path used by upload completion and other status transitions
updateMemoryStatus.invalid-status UpdateMemoryStatusInput StandardError status=500 message=Invalid status error status must be one of supported enum values
updateMemoryStatus.memory-not-found UpdateMemoryStatusInput StandardError status=500 message=Memory not found error target memory row must exist

Flow: updateMemoryUploadProgress

  • Test files: main/server/tests/unit/test_memory_orm.py
  • Core files: main/server/layers/shared/python/shared/orm/memory_orm.py

Type Definitions

UpdateMemoryUploadProgressInput {
  memory_id: string (required)
  completed_upload_count: number (required; >= 0)
  failed_upload_count: number (required; >= 0)
}

UpdateMemoryUploadProgressOutput {
  expected_upload_count: number
  completed_upload_count: number
  failed_upload_count: number
}

Paths

path-name input output/expected state change path-type notes updated
updateMemoryUploadProgress.success UpdateMemoryUploadProgressInput UpdateMemoryUploadProgressOutput; MemoryOrm completed_upload_count and failed_upload_count are updated happy path used by upload completion to persist terminal counts before status transition decisions
updateMemoryUploadProgress.invalid-counts UpdateMemoryUploadProgressInput StandardError status=500 message=Invalid upload progress counts error counts must be non-negative and not exceed expected_upload_count
updateMemoryUploadProgress.memory-not-found UpdateMemoryUploadProgressInput StandardError status=500 message=Memory not found error target memory row must exist

Flow: updateMemoryEmbedding

  • Test files: main/server/tests/unit/test_memory_orm.py, main/server/tests/unit/test_memories_pipeline_ingest_app.py
  • Core files: main/server/layers/shared/python/shared/orm/memory_orm.py, main/server/memories/pipeline/ingest/app.py

Type Definitions

UpdateMemoryEmbeddingInput {
  memory_id: string (required)
  embedding_vector: MemoryEmbeddingVector (required)
}

UpdateMemoryEmbeddingOutput {
  value: void (side-effect only; writes embedding and sets processed status)
}

Paths

path-name input output/expected state change path-type notes updated
updateMemoryEmbedding.success UpdateMemoryEmbeddingInput UpdateMemoryEmbeddingOutput; MemoryOrm.embedding_vector is persisted and memory_upload_status becomes processed happy path ingest completion contract
updateMemoryEmbedding.invalid-vector-type UpdateMemoryEmbeddingInput StandardError status=500 message=Invalid embedding vector error embedding vector must be a list of numeric values
updateMemoryEmbedding.invalid-vector-dimension UpdateMemoryEmbeddingInput StandardError status=500 message=Invalid embedding vector dimension error vector length must be exactly 384
updateMemoryEmbedding.memory-not-found UpdateMemoryEmbeddingInput StandardError status=500 message=Memory not found error target memory row must exist

3. Pseudocode / Technical Details for Critical Flows (Optional)

Skipped by request: contract-only ORM plan focused on type definition and method I/O.

After all stages are approved, apply .agent/skills/reconcile-plans/SKILL.md to propagate contract updates across linked plans.