> ## Documentation Index > Fetch the complete documentation index at: https://docs.flumes.ai/llms.txt > Use this file to discover all available pages before exploring further. # Hybrid retrieval over facts/events/documents with tunable weights. ## OpenAPI ````yaml api-reference/flumes.yaml post /v0/recall openapi: 3.1.0 info: title: Flumes Memory API (MVP) version: 0.9.2 description: > Unified memory + context assembly for LLM agents. Core endpoints: /v0/context/assemble, /v0/memories, /v0/recall, /v0/summarize, /v0/prune, /v0/observability/events. Private endpoints (not for SDKs): /v0/extract, /v0/memories:batch_upsert. servers: - url: https://api.flumes.ai description: Production - url: https://staging.api.flumes.ai description: Staging security: - bearerAuth: [] paths: /v0/recall: post: tags: - Retrieval summary: Hybrid retrieval over facts/events/documents with tunable weights. operationId: recallMemories parameters: - $ref: '#/components/parameters/AgentHeader' requestBody: required: true content: application/json: schema: type: object properties: query: type: string maxLength: 4000 entity_id: type: string nullable: true namespace: type: string default: default filters: $ref: '#/components/schemas/Filters' sort: type: string enum: - score_desc - timestamp_desc default: score_desc cursor: type: string nullable: true limit: type: integer default: 16 maximum: 200 retrieval: $ref: '#/components/schemas/RetrievalConfig' return: $ref: '#/components/schemas/ReturnConfig' responses: '200': description: Matches with scoring headers: X-Request-Id: schema: type: string X-RateLimit-Remaining: schema: type: integer X-RateLimit-Reset: schema: type: integer Access-Control-Allow-Origin: schema: type: string content: application/json: schema: type: object properties: matches: type: array items: $ref: '#/components/schemas/Match' retrieval_summary: $ref: '#/components/schemas/RetrievalSummary' next_cursor: type: string nullable: true flags: $ref: '#/components/schemas/Flags' cost: $ref: '#/components/schemas/Cost' raw_items: type: array description: Present only when return.include_raw_memories=true items: $ref: '#/components/schemas/Memory' request_id: type: string '400': $ref: '#/components/responses/ErrorResponse' '401': $ref: '#/components/responses/ErrorResponse' '422': $ref: '#/components/responses/ErrorResponse' '429': $ref: '#/components/responses/ErrorResponse' components: parameters: AgentHeader: name: X-Flumes-Agent in: header required: false schema: type: string maxLength: 128 description: Agent id within the org. schemas: Filters: type: object properties: types: type: array items: type: string tags_any: type: array items: type: string metadata: type: object additionalProperties: true time_range: $ref: '#/components/schemas/TimeRange' RetrievalConfig: type: object properties: preset: type: string enum: - balanced - fast - factual - recent - graphy weights: $ref: '#/components/schemas/RetrievalWeights' normalization: type: string enum: - minmax - zscore - softmax default: minmax recency_half_life_days: type: integer default: 45 top_k: type: integer default: 24 minimum: 1 maximum: 100 diversity: type: object properties: enable: type: boolean default: true max_per_predicate: type: integer default: 3 max_per_source: type: integer default: 5 predicate_boosts: type: object additionalProperties: type: number entity_boosts: type: array items: type: string depth: type: integer default: 2 minimum: 0 maximum: 2 rerank: type: object properties: enable: type: boolean default: false ReturnConfig: type: object properties: include: type: array items: type: string enum: - facts - recent_events - summary - sources default: - facts - recent_events - summary - sources max_facts: type: integer default: 12 max_events: type: integer default: 6 include_scores: type: boolean default: false include_raw_memories: type: boolean default: false trace: type: boolean default: false include_structured_facts: type: boolean default: false include_raw_matches: type: boolean default: false Match: type: object properties: memory_id: type: string type: type: string text: type: string metadata: type: object additionalProperties: true score: type: number score_components: $ref: '#/components/schemas/ScoreComponents' reason: type: array items: type: string timestamp: type: string format: date-time nullable: true RetrievalSummary: type: object properties: weights_used: $ref: '#/components/schemas/RetrievalWeights' normalization: type: string depth: type: integer candidate_counts: type: object properties: semantic: type: integer bm25: type: integer graph: type: integer union: type: integer after_filters: type: integer diversity_actions: type: object properties: clamped_by_predicate: type: integer clamped_by_source: type: integer degraded: type: boolean budget_cut_count: type: integer nullable: true Flags: type: object properties: degraded: type: boolean default: false description: >- True if embeddings or a retrieval channel was unavailable and the server degraded gracefully. weights_renormalized: type: boolean default: false description: >- True if provided retrieval weights did not sum to 1 and were renormalized. Cost: type: object properties: input_tokens: type: integer default: 0 embedding: type: integer default: 0 llm_tokens: type: integer default: 0 retrieval_ops: type: integer default: 0 Memory: type: object description: >- Base memory record (open-world). Write requests ignore org fields; org is taken from header. properties: memory_id: type: string readOnly: true org_id: type: string readOnly: true namespace: type: string default: default maxLength: 64 agent_id: type: string nullable: true entity_id: type: string nullable: true type: type: string enum: - fact - event - document - note - profile - chunk text: type: string description: >- Human-readable content; for facts, this is a rendered form of subject/predicate/object. maxLength: 20000 metadata: type: object additionalProperties: true tags: type: array items: type: string maxLength: 64 timestamp: type: string format: date-time archived: type: boolean default: false sensitivity: type: string enum: - none - pii - auto default: auto subject: type: string nullable: true description: Entity id like ent:user_42 predicate: type: string nullable: true maxLength: 128 object: oneOf: - type: string maxLength: 4000 - type: number - type: boolean - type: object additionalProperties: true - type: 'null' object_type: type: string enum: - literal - string - number - date - json - entity nullable: true unit: type: string nullable: true maxLength: 32 keys: type: array items: type: string maxLength: 128 nullable: true description: Conflict keys for supersession. valid_from: type: string format: date-time nullable: true valid_to: type: string format: date-time nullable: true confidence: type: number minimum: 0 maximum: 1 nullable: true status: type: string enum: - active - superseded - disputed default: active provenance: type: object additionalProperties: true description: 'Source info; e.g., { source_turn: memory_id }' required: - type - namespace - text TimeRange: type: object properties: from: type: string format: date-time nullable: true to: type: string format: date-time nullable: true RetrievalWeights: type: object properties: semantic: type: number default: 0.45 bm25: type: number default: 0.25 graph_prior: type: number default: 0.15 recency_decay: type: number default: 0.1 confidence: type: number default: 0.05 ScoreComponents: type: object additionalProperties: type: object properties: raw: type: number norm: type: number weight: type: number contrib: type: number Error: type: object properties: error: type: string examples: - unauthorized - validation_error - rate_limited - conflict message: type: string request_id: type: string details: type: object additionalProperties: true responses: ErrorResponse: description: Error envelope headers: X-Request-Id: schema: type: string X-RateLimit-Remaining: schema: type: integer X-RateLimit-Reset: schema: type: integer description: UTC seconds until limit resets Access-Control-Allow-Origin: schema: type: string description: Present if CORS enabled content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: APIKey ````