> ## 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 accepts the structured filter expression language. User-defined metadata keys must be referenced with the `m.` or `metadata.` prefix (for example, `m.source = "chat_v3"`). Unknown or unsupported fields are rejected instead of being ignored. The set_metadata field scopes semantic memories to matching semantic sets. The types field allows specifying which memory types to include in the search. ## OpenAPI ````yaml /openapi.json post /api/v2/memories/search openapi: 3.1.0 info: title: MemMachine API version: 0.3.10 description: >- Architectural Memory Systems for AI Agents. Specialized in episodic and semantic memory management with strict namespace isolation. servers: - url: http://localhost:8080 security: [] tags: - name: Configuration description: System overview and memory subsystem configuration. - name: Episodic Configuration description: Per-project episodic memory subsystem configuration. - name: Memories description: Core operations for episodic and semantic memory ingestion and retrieval. - name: Projects description: Lifecycle management for isolated memory namespaces. - name: Resources description: Embedder, language model, and reranker lifecycle management. - name: 'Semantic Memory: Categories' description: Category, template, and tag management for semantic sets. - name: 'Semantic Memory: Features' description: Add, retrieve, and update individual semantic features. - name: 'Semantic Memory: Sets' description: Set type and set ID lifecycle, listing, and configuration. - name: System description: Infrastructure, health, and observability. paths: /api/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 accepts the structured filter expression language. User-defined metadata keys must be referenced with the `m.` or `metadata.` prefix (for example, `m.source = "chat_v3"`). Unknown or unsupported fields are rejected instead of being ignored. The set_metadata field scopes semantic memories to matching semantic sets. The types field allows specifying which memory types to include in the search. operationId: search_memories requestBody: content: application/json: schema: $ref: '#/components/schemas/SearchMemoriesSpec' required: true responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/SearchResult' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' components: schemas: SearchMemoriesSpec: properties: org_id: type: string title: Org Id description: |2- The unique identifier of the organization. - Must not contain slashes (`/`). - Must contain only letters, numbers, underscores, hyphens, colon, and Unicode characters (e.g., Chinese/Japanese/Korean). No slashes or other symbols are allowed. This value determines the namespace the project belongs to. default: universal examples: - MemVerge - AI_Labs project_id: type: string title: Project Id description: |2- The identifier of the project. - Must be unique within the organization. - Must not contain slashes (`/`). - Must contain only letters, numbers, underscores, hyphens, colon, and Unicode characters (e.g., Chinese/Japanese/Korean). No slashes or other symbols are allowed. This ID is used in API paths and resource locations. default: universal examples: - memmachine - research123 - qa_pipeline top_k: type: integer title: Top K description: |2- The maximum number of memories to return in the search results. default: 10 examples: - 5 - 10 - 20 query: type: string title: Query description: |2- The natural language query used for semantic memory search. This should be a descriptive string of the information you are looking for. examples: - What was the user's last conversation about finance? filter: type: string title: Filter description: |2- 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. default: '' examples: - metadata.user_id=123 AND metadata.session_id=abc set_metadata: anyOf: - additionalProperties: $ref: '#/components/schemas/JsonValue' type: object - type: 'null' title: Set Metadata description: |2- Optional metadata key-value pairs used to filter or identify semantic sets. expand_context: type: integer title: Expand Context description: |2- The number of additional episodes to include around each matched episode from long term memory for better context. default: 0 examples: - 0 - 3 - 6 score_threshold: anyOf: - type: number - type: 'null' title: Score Threshold description: |2- 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. examples: - 0 - 0.5 - null types: items: $ref: '#/components/schemas/MemoryType' type: array title: Types description: |2- A list of memory types to include in the search (e.g., episodic, semantic). If empty, all available types are searched. examples: - - episodic - semantic agent_mode: type: boolean title: Agent Mode description: |2- Whether to enable top-level retrieval-agent orchestration for episodic search. When false, episodic search uses direct memory retrieval. default: false examples: - false - true type: object required: - query title: SearchMemoriesSpec description: Specification model for searching memories. SearchResult: properties: status: type: integer title: Status description: |2- The status code of the search operation. 0 typically indicates success. default: 0 examples: - 0 content: $ref: '#/components/schemas/SearchResultContent' description: |2- The dictionary containing the memory search results (e.g., list of memory objects). type: object required: - content title: SearchResult description: Response model for memory search results. HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError JsonValue: {} MemoryType: type: string enum: - semantic - episodic title: MemoryType description: Memory type. SearchResultContent: properties: episodic_memory: anyOf: - $ref: '#/components/schemas/EpisodicSearchResult' - type: 'null' description: Episodic memory search results. semantic_memory: anyOf: - items: $ref: '#/components/schemas/SemanticFeature' type: array - type: 'null' title: Semantic Memory description: Semantic memory search results. additionalProperties: false type: object title: SearchResultContent description: Payload for SearchResult.content returned by `/memories/search`. ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type type: object required: - loc - msg - type title: ValidationError EpisodicSearchResult: properties: long_term_memory: $ref: '#/components/schemas/EpisodicSearchLongTermMemory' description: Long-term episodic search results. short_term_memory: $ref: '#/components/schemas/EpisodicSearchShortTermMemory' description: Short-term episodic search results. type: object required: - long_term_memory - short_term_memory title: EpisodicSearchResult description: Episodic payload returned by `/memories/search`. SemanticFeature: properties: set_id: anyOf: - type: string - type: 'null' title: Set Id description: Identifier of the semantic set. category: type: string title: Category description: Category of the semantic feature. tag: type: string title: Tag description: Tag associated with the semantic feature. feature_name: type: string title: Feature Name description: Name of the semantic feature. value: type: string title: Value description: Value of the semantic feature. metadata: $ref: '#/components/schemas/Metadata' description: Storage metadata for the semantic feature. type: object required: - category - tag - feature_name - value title: SemanticFeature description: Semantic memory entry returned in API responses. EpisodicSearchLongTermMemory: properties: episodes: items: $ref: '#/components/schemas/EpisodeResponse' type: array title: Episodes description: Matched long-term episodic entries. type: object required: - episodes title: EpisodicSearchLongTermMemory description: Long-term episodic memory search results. EpisodicSearchShortTermMemory: properties: episodes: items: $ref: '#/components/schemas/EpisodeResponse' type: array title: Episodes description: Matched short-term episodic entries. episode_summary: items: type: string type: array title: Episode Summary description: Summaries of matched short-term episodes. type: object required: - episodes - episode_summary title: EpisodicSearchShortTermMemory description: Short-term episodic memory search results. Metadata: properties: citations: anyOf: - items: type: string type: array - type: 'null' title: Citations description: Episode IDs cited by this semantic feature. id: anyOf: - type: string - type: 'null' title: Id description: Identifier for the semantic feature. other: anyOf: - additionalProperties: true type: object - type: 'null' title: Other description: Additional storage metadata for the semantic feature. type: object title: Metadata description: Storage metadata for a semantic feature, including id and citations. EpisodeResponse: properties: content: type: string title: Content description: The content payload of the episode. producer_id: type: string title: Producer Id description: Identifier of the episode producer. producer_role: type: string title: Producer Role description: Role of the producer (e.g., user/assistant/system). produced_for_id: anyOf: - type: string - type: 'null' title: Produced For Id description: Identifier of the intended recipient of the episode. episode_type: anyOf: - $ref: '#/components/schemas/EpisodeType' - type: 'null' description: The type of episode being stored (e.g., message). metadata: anyOf: - additionalProperties: $ref: '#/components/schemas/JsonValue' type: object - type: 'null' title: Metadata description: Optional metadata associated with the episode. created_at: anyOf: - type: string format: date-time - type: 'null' title: Created At description: Timestamp when the episode was created. uid: type: string title: Uid description: Unique identifier for the episode. score: anyOf: - type: number - type: 'null' title: Score description: Optional relevance score for the episode. type: object required: - content - producer_id - producer_role - uid title: EpisodeResponse description: Episode data returned in search responses. EpisodeType: type: string enum: - message title: EpisodeType description: Episode type. ````