--- title: "Search memories" method: POST path: "/v1/memories/search" tags: ["Memories"] --- # Search memories `POST /v1/memories/search` Perform a search query across your memories. **Standard mode** (collection_ids or readable-scope search): returns hierarchical MemoryRecall with semantics, episodes, procedures, and sources. **Snapshot mode** (snapshot field): returns graph-search results with {entities, relationships} from stateless in-memory traversal. ## Request body - MemorySearchRequest — Request model for memory search. Callers must supply exactly one of ``query`` or ``nql``. ``query`` takes the planner path; ``nql`` executes a hand-written script directly for deterministic test/tooling use cases. - `collection_ids` string[], nullable — Optional list of collection UUIDs or names to scope the search. - `effort` 'auto' | 'low' | 'medium' | 'high' — Compute effort budget for memory search. Effort controls traversal compute (exploration budgets, depth, fanout), not the size of the returned MemoryRecall projection. - `filters` object, nullable — Optional filters to apply to the search. - `nql` string, nullable — Pre-written NQL script. Executes directly without planner compilation. Mutually exclusive with ``query``. - `query` string, nullable — Natural-language search query. Mutually exclusive with ``nql``. - `search_settings` SearchSettings — Advanced search settings for fine-tuning search behavior. Note: Core parameters (query, collection_ids, filters) are now top-level API parameters. This class contains advanced tuning options plus internal fields used by the retrieval service. Memory search uses `effort` (auto/low/medium/high) to control compute. - `effort` 'auto' | 'low' | 'medium' | 'high' — Compute effort budget for memory search. Effort controls traversal compute (exploration budgets, depth, fanout), not the size of the returned MemoryRecall projection. - `enable_conceptual_expansion` boolean — Enable conceptual expansion for cross-domain discovery through overlapping concepts - `filters` object — Internal: Filters populated by the API router - `fulltext_weight` number — Weight for fulltext search in hybrid mode (0-1). Set to 0 for pure semantic search. - `graph_settings` object — Internal: Graph traversal settings (bfs_max_depth, semantic_threshold, etc.) - `has_pruning_gate` boolean — Internal: Set by select_search_filters when an owner_id $in partition-pruning wrapper has been added around the filter tree. Used by the in-memory graph read engine to strip the Postgres-only wrapper before evaluating delegation. - `include_scores` boolean — Whether to include search score values in the search results - `semantic_weight` number — Weight for semantic search in hybrid mode (0-1). Set to 0 for pure fulltext search. - `verbose` boolean — Include full internal metadata, UUIDs, and confidence fields in MemoryRecall responses. When False, returns compact LLM-optimized format. - `snapshot` SnapshotEnvelopeInput — Portable full snapshot owned by the client. - `collection_id` string, uuid, required - `created_at` string, date-time - `format_version` integer - `generation` integer - `graph` GraphPayload — A complete graph payload or a context subgraph payload. - `entities` EntityRecord[] - `category` string, nullable - `chunk_ids` string[] - `collection_id` string - `created_at` string, date-time, required - `description` string, nullable - `engram_id` string, required - `fts_terms` object, nullable - `id` string, required - `metadata` object - `name` string, required - `relationship_count` integer - `updated_at` string, date-time, required - `entity_description_embeddings` EmbeddingBlock — A positionally-aligned masked embedding matrix. - `dim` integer - `encoding` 'npy-base64' - `mask_b64` string - `values_b64` string - `relationship_description_embeddings` EmbeddingBlock — A positionally-aligned masked embedding matrix. - `dim` integer - `encoding` 'npy-base64' - `mask_b64` string - `values_b64` string - `relationship_relation_embeddings` EmbeddingBlock — A positionally-aligned masked embedding matrix. - `dim` integer - `encoding` 'npy-base64' - `mask_b64` string - `values_b64` string - `relationships` RelationshipRecord[] - `category` string, nullable - `chunk_ids` string[] - `collection_id` string - `created_at` string, date-time, required - `description` string, nullable - `engram_id` string, nullable - `id` string, required - `inference_metadata` object, nullable - `metadata` object - `object` string, nullable - `object_id` string, required - `predicate` string - `relationship_type` string, nullable - `subject` string, nullable - `subject_id` string, required - `temporal_precision` string, nullable - `updated_at` string, date-time, required - `valid_span` object, nullable - `weight` number, nullable - `root_hash` string, required ## Response `200` Successful Response - union - NebulaResultsCompactMemoryRecallResponse - `results` CompactMemoryRecallResponse, required — Default compact response from /v1/memories/search. - `episodic` object[] - `procedural` object[] - `query` string, required - `semantic` object[] - `sources` object[] - `token_count` integer - NebulaResultsMemoryRecall - `results` MemoryRecall, required — Hierarchical memory response - all layers, weighted by activation. This is the primary response type for conceptual memory retrieval. It contains all layers of the memory hierarchy: 1. **Entities (gestalt/schema layer)**: EntityProfiles that represent the conceptual understanding of activated entities. 2. **Semantics (semantic layer)**: Structured assertions (facts, inferences, tasks) scored by relevance and confidence. 3. **Episodes (temporal clusters)**: Episodic nodegroups that cluster temporally related facts and events. 4. **Sources (episodic layer)**: The raw source material that grounds the structured knowledge in actual moments/quotes. - `entities` ActivatedEntity[] - `activation_score` number - `category` string, nullable - `id` string, uuid, required - `name` string, required - `profile` unknown - `episodic` ActivatedEpisode[] - `activation_score` number - `category` string - `description` string, nullable - `entity_names` string[] - `evidence_ids` string[] - `id` string, uuid, required - `member_semantic_ids` string[] - `n_facts` integer - `name` string, required - `status` string, nullable - `t_last` string, nullable - `t_start` string, nullable - `inference_hints` InferenceHint[] - `confidence` number, nullable - `inference_metadata` object, nullable - `inferred` boolean - `ledger_p_stable` number, nullable - `ledger_p_true` number, nullable - `ledger_p_use` number, nullable - `metadata` object, nullable - `object` string, required - `object_id` string, uuid, nullable - `predicate` string, required - `relationship_id` string, uuid, nullable - `subject_id` string, uuid, nullable - `term` string, required - `usable_for_rewrite` boolean - `used_for_rewrite` boolean - `procedural` ActivatedProcedure[] - `activation_score` number - `belief_kind` string, nullable - `confidence` number - `derivation_type` string - `entity_id` string, uuid, nullable - `entity_name` string, nullable - `id` string, uuid, required - `is_negated` boolean - `metadata` object, nullable - `statement` string, required - `query` string, required - `semantic` ActivatedSemantic[] - `activation_score` number - `belief_kind` string, nullable - `category` string - `corroboration_count` integer - `description` string, nullable - `entity_id` string, uuid, nullable - `entity_name` string, nullable - `evidence_ids` string[] - `evidence_refs` EvidenceRef[] - `artifact_id` string, uuid, nullable - `chunk_id` string, uuid, nullable - `collection_id` string, uuid, nullable - `column_names` string[], nullable - `ref_type` 'chunk' | 'table_artifact', required - `row_indices` integer[], nullable - `table_name` string, nullable - `extraction_confidence` number - `id` string, uuid, required - `is_current` boolean, nullable - `predicate` string, required - `reasoning` string, nullable - `resolved_at` string, nullable - `source_nodegroup_ids` string[] - `stability_confidence` number, nullable - `subject` string, required - `temporal_precision` string, nullable - `temporal_validity` unknown - `truth_confidence` number, nullable - `use_confidence` number, nullable - `value` string, required - `sources` GroundedSource[] - `activation_score` number - `display_name` string, nullable - `engram_id` string, uuid, nullable - `evidence_ref` EvidenceRef — Tagged reference to a source of evidence. - `artifact_id` string, uuid, nullable - `chunk_id` string, uuid, nullable - `collection_id` string, uuid, nullable - `column_names` string[], nullable - `ref_type` 'chunk' | 'table_artifact', required - `row_indices` integer[], nullable - `table_name` string, nullable - `id` string, uuid, required - `metadata` object, nullable - `owner_id` string, uuid, nullable - `page_number` integer, nullable - `section_path` string[], nullable - `source_role` string, nullable - `speaker` string, nullable - `speaker_id` string, uuid, nullable - `structure_label` string, nullable - `supporting_fact_ids` string[] - `text` string, required - `timestamp` string, date-time, nullable - `total_traversal_time_ms` number, nullable - NebulaResultsSnapshotSearchResult - `results` SnapshotSearchResult, required — Stateless snapshot-search response shape. - `entities` SnapshotSearchEntityResponse[] - `category` string, nullable - `description` string, nullable - `id` string, uuid, required - `name` string, required - `score` number, required - `relationships` SnapshotSearchRelationshipResponse[] - `description` string, nullable - `id` string, uuid, required - `object_id` string, uuid, required - `predicate` string, required - `subject_id` string, uuid, required - `weight` number, nullable ## Other responses - `422` — Validation Error --- [API](https://skmtc.net/zeroset-inc/apis/nebula-api.md) · [All operations](https://skmtc.net/zeroset-inc/apis/nebula-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/zeroset-inc/nebula-api/revisions/b1da2c0bb1ae/schema)