Skip to content

Memory Search

Plan Metadata

  • Plan type: plan
  • Parent plan: N/A
  • Depends on:
  • shared-lambda-interface.md
  • Status: documentation

System Intent

  • What is being built: Source-of-truth contract for the /memories/search API surface and its mobile client wrapper.
  • Primary consumer(s): searchMemories API wrapper and useSearchMemories query usage.
  • Boundary (black-box scope only): Request validation on the client, /memories/search request/response shape, and current server-side runtime behavior.

Stage Gate Tracker

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

1. Mermaid Diagram

Reference: .agent/skills/create-mermaid-diagram/SKILL.md

flowchart TD
  A[Search Client Wrapper - main/app/lib/api/memory/searchMemories.ts] -->|POST /memories/search payload| B[Memories Search Lambda - main/server/api/memories/search/app.py]
  C[Search Query Hook - main/app/lib/api/memory/useMemoryApi.ts] -->|query trigger with payload query| A
  B -->|runtime error response via invoke_lambda| A
  A -->|resolved results or thrown error| C

  classDef unchanged fill:#d3d3d3,stroke:#666,stroke-width:1px;
  classDef updated fill:#ffe58a,stroke:#666,stroke-width:1px;
  classDef deleted fill:#f4a6a6,stroke:#666,stroke-width:1px;
  classDef created fill:#a8e6a3,stroke:#666,stroke-width:1px;

  class A,B,C unchanged;

2. Black-Box Inputs and Outputs

Global Types

SearchMemoriesPayload {
  query: string (required, min length 1)
  limit?: number
  threshold?: number
  start_time?: number
  end_time?: number
  device_id?: string
  latitude?: number
  longitude?: number
  radius_meters?: number
}

BlobRef {
  type: string
  s3_key: string
  size?: number
}

MemorySearchResult {
  event_id: string
  modality: string
  created_at: string
  blob_refs: BlobRef[]
  score: number | null
}

SearchMemoriesResponse {
  results: MemorySearchResult[]
}

StandardError {
  status?: number
  code?: string
  message: string
}

Flow: main/app/lib/api/memory/searchMemories.ts.searchMemories, main/app/__tests__/search-memories-api.test.ts

Type Definitions

SearchClientInput = SearchMemoriesPayload
SearchClientOutput = Promise<SearchMemoriesResponse>

Paths

path-name input output/expected state change path-type notes updated
search-client.success SearchClientInput with valid query and backend success SearchClientOutput resolves to SearchMemoriesResponse happy path client returns response.data.data
search-client.invalid-query SearchClientInput with empty query StandardError message=<zod validation error> error request is rejected before network call
search-client.request-failure SearchClientInput with backend/network error StandardError message=<transport or backend error> error axios error is propagated to caller

Flow: main/server/api/memories/search/app.py.implementation, main/server/tests/unit/test_memories_search_app.py

Type Definitions

SearchLambdaInput = SearchMemoriesPayload
SearchLambdaOutput = SearchMemoriesResponse

Paths

path-name input output/expected state change path-type notes updated
search-lambda.unimplemented SearchLambdaInput any payload StandardError status=500 message=Search is not set up error current implementation always raises RuntimeError("Search is not set up")

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

  • Stage 3 decision: skipped.
  • Reason: no additional implementation detail is required beyond current API contract and explicit unimplemented-server behavior.

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