Memory API

Plan Metadata

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

Status semantics: - draft: Plan is being created or updated and is not final. - approved: Plan is approved but not yet applied in code. - documentation: Code currently exists and matches the plan contract.

Update rule: - When an existing plan is edited, set status to draft until re-approved.

System Intent

• What is being built: Unified memory API contract for session lifecycle, query execution, and session feed retrieval.
• Primary consumer(s): API callers (app, CLI, and backend-integrated clients).
• Boundary (black-box scope only): dummy endpoint behavior for startSession, queryMemories, and fetchSessions, where each endpoint returns random but contract-shaped output.

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[API Caller] -->|POST /sessions/session body.session_id?| B[session Lambda - main/server/api/sessions/session/app.py]
  B -->|StartSessionResponse| A
  A -->|POST /sessions/query| C[queryMemories Lambda - main/server/api/sessions/query/app.py]
  A -->|POST /sessions/feed| D[fetchSessions Lambda - main/server/api/sessions/feed/app.py]
  C -->|QueryMemoriesResponse| A
  D -->|FetchSessionsResponse| 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,D unchanged;

2. Black-Box Inputs and Outputs

Temporary Execution Mode (Dummy API First)

• Current execution target is a dummy API implementation that does not require persistence.
• startSession: return random SessionMetadata; if session_id is provided, echo it in the response metadata.
• queryMemories: return a random placeholder answer and optionally echo conversation.
• fetchSessions: return random/synthetic SessionMetadata and random paginated queries.
• Auth middleware remains required for all endpoints in this phase.
• Error handling and ownership enforcement beyond auth are intentionally out of scope for this dummy phase.

Legacy API Replacement Notes (Executed)

Endpoint Contract

Global Types

SessionMetadata {
  session_id: string
  title?: string
  created_at: string (ISO-8601 timestamp)
  updated_at: string (ISO-8601 timestamp)
  message_count: number
}

SessionMessage {
  message_id: string
  session_id?: string
  role: "user" | "assistant"
  content: string
  created_at: string (ISO-8601 timestamp)
}

StartSessionRequest {
  session_id?: string
}

StartSessionResponse {
  session: SessionMetadata
}

SearchMemoriesPayload {
  conversation?: string (session id)
  query: string
}

QueryMemoriesRequest = SearchMemoriesPayload

QueryMemoriesResponse {
  answer: string
  conversation?: string (session id when query is session-bound)
}

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

FetchSessionsResponse {
  session: SessionMetadata
  queries: SessionMessage[] (ordered most-recent-first)
  next_cursor?: string | null
}

Flow: main/server/api/sessions/session/app.py.implementation

• Test files: main/server/tests/unit/test_sessions_session_app.py
• Core files: main/server/api/sessions/session/app.py
• Replaces: N/A (new API capability)

Type Definitions

StartSessionLambdaInput = StartSessionRequest
StartSessionLambdaOutput = StartSessionResponse

Paths

Flow: main/server/api/sessions/query/app.py.implementation

• Test files: main/server/tests/unit/test_sessions_query_app.py
• Core files: main/server/api/sessions/query/app.py
• Replaces: POST /memories/search (main/server/api/memories/search/app.py, deleted after migration)

Type Definitions

SessionsQueryLambdaInput = QueryMemoriesRequest
SessionsQueryLambdaOutput = QueryMemoriesResponse

Paths

Flow: main/server/api/sessions/feed/app.py.implementation

• Test files: main/server/tests/unit/test_sessions_feed_app.py
• Core files: main/server/api/sessions/feed/app.py
• Replaces: POST /conversations/feed (main/server/api/conversations/feed/app.py, deleted after migration)

Type Definitions

SessionsFeedLambdaInput = FetchSessionsRequest
SessionsFeedLambdaOutput = FetchSessionsResponse

Paths

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

Dummy Output Rules

• Pseudocode intent for this phase: just return correct-looking response shapes; nothing serious (no persistence, no retrieval, no ownership/data-layer enforcement).
• startSession returns random SessionMetadata with contract-valid timestamps.
• queryMemories returns a random placeholder answer string.
• fetchSessions returns random session metadata and random message rows in the expected response shape.

startSession(payload):
  return {
    session: randomContractSessionMetadata(
      session_id = payload.session_id if provided else random_id()
    )
  }

queryMemories(payload):
  return {
    answer: random_placeholder_string(),
    conversation: payload.conversation if provided else omitted
  }

fetchSessions(payload):
  return {
    session: randomContractSessionMetadata(session_id = payload.session_id),
    queries: randomContractMessages(limit = payload.limit or 20),
    next_cursor: random_or_null_cursor()
  }

4. Handoff to Related Plan Reconciliation

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