Skip to content

Memory Feed

Plan Metadata

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

System Intent

  • What is being built: Contract for the mobile memories feed list flow.
  • Primary consumer(s): useMemoriesFeed hook, listMemories API wrapper, and memories feed lambda handler.
  • Boundary (black-box scope only): feed pagination request/response behavior for /memories/feed.

Stage Gate Tracker

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

1. Mermaid Diagram

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

flowchart TD
  A[Memories Feed Hook - main/app/lib/api/memory/useMemoryApi.ts] -->|requests next page with cursor and limit| B[List Memories Client - main/app/lib/api/memory/listMemories.ts]
  B -->|POST /memories/feed payload| C[Memories Feed Lambda - main/server/api/memories/feed/app.py]
  C -->|memories page and next_cursor| B
  B -->|paginated feed response| A

  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

Keep this short. Define types in JSON-style blocks and capture each flow with path-level rows.

Global Types

Define shared types used across multiple flows. This plan is the canonical pagination contract for feed-style endpoints (cursor nullable string, limit int 1..50 default 20), reused by conversation-feed.md.

ListMemoriesInput {
  cursor?: string | null
  limit?: number (int, 1..50, default=20)
}

MemoryFeedItem {
  id: string
  time: string
  url: string
  featured?: boolean
}

ListMemoriesOutput {
  memories: MemoryFeedItem[]
  next_cursor?: string | null
}

ListMemoriesFunction {
  input: ListMemoriesInput
  output: Promise<ListMemoriesOutput>
}

MemoriesFeedCacheKey {
  value: ["memories", "feed", ListMemoriesInput]
}

UseMemoriesFeedInput {
  params?: ListMemoriesInput
}

UseMemoriesFeedResult {
  pages: ListMemoriesOutput[]
  next_page_param?: string
  cache_key: MemoriesFeedCacheKey
}

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

Flow: main/app/app/index.tsx.MemoriesScreen, main/app/__tests__/memory-feed-screen.test.tsx

Type Definitions

MemoriesScreenIntegrationInput {
  feed_request: UseMemoriesFeedInput
  user_action?: "open_memory" | "submit_search"
}

MemoriesScreenIntegrationOutput {
  visible_memories: MemoryFeedItem[]
  load_more_visible: boolean
  memory_viewer_visible?: boolean
  navigation_target?: "/chat"
  navigation_query?: string
  feed_state: UseMemoriesFeedResult
}

Paths

path-name input output/expected state change path-type notes updated
memory-feed-screen.initial-feed-visible MemoriesScreenIntegrationInput with feed_request.params.limit=20 and feed page where next_cursor exists MemoriesScreenIntegrationOutput visible_memories populated; load_more_visible=true happy path validates usable landing state: feed content is shown and more content can be requested; feed_state.pages originates from ListMemoriesFunction outputs
memory-feed-screen.open-viewer MemoriesScreenIntegrationInput with user_action=open_memory on a visible tile MemoriesScreenIntegrationOutput memory_viewer_visible=true happy path selecting a memory opens viewer modal for reading details
memory-feed-screen.search-to-chat MemoriesScreenIntegrationInput with user_action=submit_search and non-empty query MemoriesScreenIntegrationOutput navigation_target=/chat navigation_query=<trimmed_query> happy path usable path from feed screen to chat seeded with search text

Flow: main/app/lib/api/memory/listMemories.ts.listMemories, main/app/__tests__/memory-feed-api.test.ts

Type Definitions

ListMemoriesFunctionInput = ListMemoriesInput
ListMemoriesFunctionOutput = Promise<ListMemoriesOutput>

Paths

path-name input output/expected state change path-type notes updated
list-memories.first-page ListMemoriesFunctionInput limit=10 ListMemoriesFunctionOutput resolves to ListMemoriesOutput with memories.length=10 and next_cursor set happy path core paginated fetch behavior used by feed screen
list-memories.end-of-feed ListMemoriesFunctionInput cursor=<last_page_cursor> limit=10 ListMemoriesFunctionOutput resolves to ListMemoriesOutput with next_cursor=null subpath signals no further pages so UI can hide or disable load-more affordance
list-memories.invalid-cursor ListMemoriesFunctionInput cursor=not-a-number StandardError message=Invalid cursor error rejects malformed cursor before backend fetch

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

  • Stage 3 decision: skipped.
  • Reason: no additional implementation-critical details exist beyond Section 2 contracts and approved integration-flow paths.

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