> ## Documentation Index > Fetch the complete documentation index at: https://docs.memmachine.ai/llms.txt > Use this file to discover all available pages before exploring further. # Search Memories > Search memories within a project. System returns the top K relevant memories matching the natural language query. The result is sorted by timestamp to help with context. The filter field allows for filtering based on metadata key-value pairs. The types field allows specifying which memory types to include in the search. ## OpenAPI ````yaml /platform.openapi.json post /v2/memories/search openapi: 3.0.4 info: description: >- Public REST API for the MemMachine memory system. Manages projects and memories. title: MemMachine Public API version: 0.1.0 servers: - url: https://api.memmachine.ai security: - BearerAuth: [] tags: - name: Projects - name: Memories - name: Metrics - name: Health paths: /v2/memories/search: post: tags: - Memories summary: Search Memories description: > Search memories within a project. System returns the top K relevant memories matching the natural language query. The result is sorted by timestamp to help with context. The filter field allows for filtering based on metadata key-value pairs. The types field allows specifying which memory types to include in the search. operationId: SearchMemories requestBody: content: application/json: schema: $ref: '#/components/schemas/SearchMemoriesSpec' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/SearchResult' description: Successful Response default: $ref: '#/components/responses/UnexpectedError' components: schemas: SearchMemoriesSpec: allOf: - $ref: '#/components/schemas/ProjectScope' - properties: agent_mode: default: false description: > Whether to enable top-level retrieval-agent orchestration for episodic search. When false, episodic search uses direct memory retrieval. example: false title: Agent Mode type: boolean expand_context: default: 0 description: | The number of additional episodes to include around each matched episode from long term memory for better context. example: 0 title: Expand Context type: integer filter: default: '' description: > An optional string filter applied to the memory metadata. This uses a simple query language (e.g., 'metadata.user_id=123') for exact matches. Multiple conditions can be combined using AND operators. The metadata fields are prefixed with 'metadata.' to distinguish them from other fields. example: metadata.user_id=123 AND metadata.session_id=abc title: Filter type: string query: description: > The natural language query used for semantic memory search. This should be a descriptive string of the information you are looking for. example: What was the user's last conversation about finance? title: Query type: string score_threshold: description: > The minimum score for a memory to be included in the search results. Defaults to -inf (no threshold) represented as None. Meaningful only for certain ranking methods. example: 0 nullable: true title: Score Threshold type: number set_metadata: additionalProperties: true description: | Optional metadata key-value pairs used to filter or identify a specific semantic memory set. Applies only when searching semantic memories. nullable: true title: Set Metadata type: object top_k: default: 10 description: | The maximum number of memories to return in the search results. example: 5 title: Top K type: integer types: description: > A list of memory types to include in the search (e.g., episodic, semantic). If empty, all available types are searched. example: - episodic - semantic items: $ref: '#/components/schemas/MemoryType' title: Types type: array required: - query type: object description: Specification model for searching memories. title: SearchMemoriesSpec SearchResult: description: Response model for memory search results. properties: content: $ref: '#/components/schemas/SearchResultContent' status: default: 0 description: > The status code of the search operation. 0 typically indicates success. example: 0 title: Status type: integer required: - content title: SearchResult type: object ProjectScope: properties: project_id: default: '' description: >- The identifier of the project. If empty, the user's default project is used. maxLength: 255 pattern: ^[\p{L}\p{N}_:-]*$ title: Project Id type: string x-go-type-skip-optional-pointer: true type: object MemoryType: description: Memory type. enum: - semantic - episodic title: MemoryType type: string SearchResultContent: additionalProperties: false description: Payload for SearchResult.content returned by `/memories/search`. properties: episodic_memory: $ref: '#/components/schemas/EpisodicSearchResult' semantic_memory: description: Semantic memory search results. items: $ref: '#/components/schemas/SemanticFeature' nullable: true title: Semantic Memory type: array title: SearchResultContent type: object Error: properties: code: description: Error code. format: int32 type: integer message: description: Error message. type: string required: - code - message type: object EpisodicSearchResult: description: Episodic payload returned by `/memories/search`. properties: long_term_memory: $ref: '#/components/schemas/EpisodicSearchLongTermMemory' short_term_memory: $ref: '#/components/schemas/EpisodicSearchShortTermMemory' required: - long_term_memory - short_term_memory title: EpisodicSearchResult type: object SemanticFeature: description: Semantic memory entry returned in API responses. properties: category: description: Category of the semantic feature. title: Category type: string feature_name: description: Name of the semantic feature. title: Feature Name type: string metadata: $ref: '#/components/schemas/Metadata' set_id: description: Identifier of the semantic set. nullable: true title: Set Id type: string tag: description: Tag associated with the semantic feature. title: Tag type: string value: description: Value of the semantic feature. title: Value type: string required: - category - tag - feature_name - value title: SemanticFeature type: object EpisodicSearchLongTermMemory: description: Long-term episodic memory search results. properties: episodes: description: Matched long-term episodic entries. items: $ref: '#/components/schemas/EpisodeResponse' title: Episodes type: array required: - episodes title: EpisodicSearchLongTermMemory type: object EpisodicSearchShortTermMemory: description: Short-term episodic memory search results. properties: episode_summary: description: Summaries of matched short-term episodes. items: type: string title: Episode Summary type: array episodes: description: Matched short-term episodic entries. items: $ref: '#/components/schemas/EpisodeResponse' title: Episodes type: array required: - episodes - episode_summary title: EpisodicSearchShortTermMemory type: object Metadata: description: Storage metadata for a semantic feature, including id and citations. properties: citations: description: Episode IDs cited by this semantic feature. items: type: string nullable: true title: Citations type: array id: description: Identifier for the semantic feature. nullable: true title: Id type: string other: additionalProperties: true description: Additional storage metadata for the semantic feature. nullable: true title: Other type: object title: Metadata type: object EpisodeResponse: description: Episode data returned in search responses. properties: content: description: The content payload of the episode. title: Content type: string created_at: description: Timestamp when the episode was created. format: date-time nullable: true title: Created At type: string episode_type: $ref: '#/components/schemas/EpisodeType' metadata: additionalProperties: true description: Optional metadata associated with the episode. nullable: true title: Metadata type: object produced_for_id: description: Identifier of the intended recipient of the episode. nullable: true title: Produced For Id type: string producer_id: description: Identifier of the episode producer. title: Producer Id type: string producer_role: description: Role of the producer (e.g., user/assistant/system). title: Producer Role type: string score: description: Optional relevance score for the episode. nullable: true title: Score type: number uid: description: Unique identifier for the episode. title: Uid type: string required: - content - producer_id - producer_role - uid title: EpisodeResponse type: object EpisodeType: default: message description: Episode type. enum: - message title: EpisodeType type: string responses: UnexpectedError: content: application/json: schema: $ref: '#/components/schemas/Error' description: Unexpected error. securitySchemes: BearerAuth: scheme: bearer type: http ````