Search Memory

Retrieve memories using the Adaptive Retrieval Engine.

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

1. Default Behavior (Automatic Intent Detection)

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:

Route Selection: Determines if the query requires Entity Anchors (graph traversal), Temporal Filtering (date ranges), or Vector Search.
Parallel Execution: May execute multiple strategies simultaneously for complex queries (e.g., “Emails from Matteo [Entity] last week [Temporal]”).
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 (`centroid_aware`)

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 (`entity_anchor`)

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 (`temporal_range`)

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 (`direct_lookup`)

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.

Resonate (Search)

Execute a search query against the memory cluster.

Payload schema

Field	Type	Status	Description
`query`	String	REQUIRED	The natural language query.
`useDynamicScoring`	Boolean	OPTIONAL	Default: `true`. Enables the Fusion Layer’s re-ranking logic based on recency and authority.
`strategy`	String	OPTIONAL	Leave empty for Automatic Intent Detection. Use only to force a path: `direct_lookup`, `centroid_aware`, `entity_anchor`, `temporal_range`.
`options.limit`	Number	OPTIONAL	Default: `5`. Max memories to return.

curl -X POST "https://api.memorymodel.dev/v1/search" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "x-end-user-id: user_123" \
  -d '{
    "query": "What is the new deadline?",
    "useDynamicScoring": true,
    "options": {
      "limit": 3
    }
  }'

// npm install @memorymodel/client
import { MemoryClient } from '@memorymodel/client';

const client = new MemoryClient({
  apiKey: "sk_live_...",
  defaultEndUserId: "user_123"
});

const results = await client.search("What is the new deadline?", {
  limit: 3,
  strategy: "centroid_aware"
});

# pip install memory-model
from memory_model import MemoryClient

client = MemoryClient(
    api_key="sk_live_...",
    default_end_user_id="user_123"
)

results = client.search(
    "What is the new deadline?",
    limit=3,
    strategy="centroid_aware"
)

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"
    }
  ]
}

Image Search (API)

Execute a visual similarity search using an image. The system extracts visual and semantic embeddings from the provided image and retrieves visually or contextually related memories.

Payload schema (image)

Field	Type	Status	Description
`queryImage`	String	REQUIRED	Base64-encoded image string to use as the search query.
`options.limit`	Number	OPTIONAL	Default: `5`. Max memories to return.

curl -X POST "https://api.memorymodel.dev/v1/search" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "x-end-user-id: user_123" \
  -d '{
    "queryImage": "iVBORw0KGgoAAAANSUhEUgAAAAE...",
    "options": {
      "limit": 3
    }
  }'

// npm install @memorymodel/client@0.5.0
import { MemoryClient } from '@memorymodel/client';

const client = new MemoryClient({
  apiKey: "sk_live_...",
  defaultEndUserId: "user_123"
});

// Requires client v0.5.0+
const results = await client.searchImage(
  "iVBORw0KGgoAAAANSUhEUgAAAAE...",
  { limit: 3 }
);

# pip install memory-model==0.5.0
from memory_model import MemoryClient

client = MemoryClient(
    api_key="sk_live_...",
    default_end_user_id="user_123"
)

# Requires client v0.5.0+
results = client.search_image(
    image_data="iVBORw0KGgoAAAANSUhEUgAAAAE...",
    limit=3
)