Skip to main content

​
Overview

Unlike standard vector search which applies a single logic to all queries, Search Memory utilizes an Intent-Based Routing architecture.
Incoming queries are analyzed to detect specific signals (Temporal, Entity-based, or Semantic) and are routed to the execution strategy that yields the highest relevance.

​
Retrieval Architecture

Untitled Diagram 2025 12 23 115746

​
1. Default Behavior (Automatic Intent Detection)

  1. Recommended for 90% of use cases.
    When the strategy parameter is omitted in the API request, the system activates the Intent Detection Layer.     Instead of forcing a single path, the system evaluates the query against multiple models to orchestrate the retrieval:
    1. Route Selection: Determines if the query requires Entity Anchors (graph traversal), Temporal Filtering (date ranges), or Vector Search.
    2. Parallel Execution: May execute multiple strategies simultaneously for complex queries (e.g., “Emails from Matteo [Entity] last week [Temporal]”).
    3. Result Fusion: The outputs are aggregated in the Fusion Layer, where deduplication occurs and scores are normalized based on the active strategies.

​
2. Manual Strategy Overrides

Advanced users can bypass Intent Detection and force a specific execution path using the strategy parameter.

​
Adaptive Vector Strategy (centroidAwareness)

  • Architectural Role: Corresponds to the Semantic Strategy.
  • Behavior: Activates Centroid Analysis. The system measures the distance between the query and the user’s semantic centroid to automatically decide between:
    • META Mode: Broad, exploratory search (High-k).
    • SPECIFIC Mode: Narrow, precision search (Low-k).
  • Best for: Abstract concepts, themes, or when you specifically want to leverage the user’s interest profile.

​
Entity Anchor Strategy (entityAnchorStrategy)

  • Architectural Role: Corresponds to the Entity-Based Strategy.
  • Behavior: Traverses the Virtual Knowledge Graph. It locks onto specific nodes (People, Places, Organizations) and retrieves connected memories regardless of semantic vector similarity.
  • Best for: Queries focused on specific subjects where “hallucination” or fuzzy matching is unacceptable.

​
Temporal Range Strategy (temporalRangeStrategy)

  • Architectural Role: Corresponds to the Temporal Strategy.
  • Behavior: Converts the query into deterministic date-range filters. It leverages the Shift-Left timestamps (resolved at ingestion) to perform strict chronological filtering, bypassing semantic similarity.
  • Best for: Queries strictly bound by time (e.g., “History from last Q3”, “Updates from yesterday”) where chronological precision is the primary intent.

​
Direct Match Strategy (directLookupStrategy)

  • Architectural Role: Corresponds to the Direct Match Strategy.
  • Behavior: Executes an O(1) lookup bypassing the embedding engine.
  • Best for: Retrieving by known IDs or exact codes.
Execute a search query against the memory cluster.

​
Payload schema

FieldTypeStatusDescription
queryStringREQUIREDThe natural language query.
useDynamicScoringBooleanOPTIONALDefault: true. Enables the Fusion Layer’s re-ranking logic based on recency and authority.
strategyStringOPTIONALLeave empty for Automatic Intent Detection. 
Use only to force a path: directLookupStrategy
, centroidAwareness, entityAnchorStrategy, 
temporalRangeStrategy.
options.limitNumberOPTIONALDefault: 5. Max memories to return.
curl -X POST "https://api.memorymodel.dev/v1/search"  \
  -H "Content-Type: application/json" \
  -H "x-memory-cluster-access-key: sk_live_..." \
  -H "x-end-user-id: user_123" \
  -d '{
    "query": "What is the new deadline?",
    "useDynamicScoring": true,
    "options": {
      "limit": 3
    }
  }'
Include x-end-user-id only if the cluster is configured for multi‑user ingestion. If not, use a simple identifier like user_123.

​
Response Object

The response includes the finalScore (0.0 to 1.0) and searchedWithNode metadata, providing explainability on which graph node anchored the search. 
{
  "data": [
    {
      "id": "mem_abc123",
      "finalScore": 0.92,
      "payload": {
        "memory_type": "movie_preference",
        "content": "I love sci-fi movies like Blade Runner.",
        "movie_genre": "sci-fi",
        "sentiment": "positive",
        "mentioned_titles": ["Blade Runner"],
        "user_id": "user_123",
        "created_at": 1700000000000
      },
      "searchedWithNode": "node_preferences_01"
    }
  ]
}