Memories

Search Memories

Search memories using hybrid semantic + lexical search.

Search Modes

Hybrid Search (default):

  • Combines BM25-style full-text search with vector similarity
  • Better recall for exact terms (IDs, error codes, technical terms)
  • Maintains semantic understanding from vector search
  • Uses PostgreSQL's ts_rank_cd with weighted fields:
    • Title: 1.0x weight (highest priority)
    • Content: 0.4x weight
    • Tags: 0.1x weight (lowest priority)

Vector-Only Search:

  • Set hybrid=false to use only semantic vector similarity
  • Best for conceptual/semantic queries
  • Uses embeddings from Qdrant vector store

Security

All searches are:

  • Scoped to your organization automatically
  • Filtered by Row-Level Security (RLS) in PostgreSQL
  • Verified by permission checker before returning results
  • Logged in audit trail

Examples

# Hybrid search for error codes (benefits from BM25 exact matching)
GET /api/v1/memories/search?query=ERROR-404&hybrid=true

# Semantic search for concepts
GET /api/v1/memories/search?query=database performance issues&hybrid=true&hnms_mode=research

# Recent memories only (performance mode)
GET /api/v1/memories/search?query=sprint planning&hybrid=true&hnms_mode=performance&limit=20

# Team-scoped search
GET /api/v1/memories/search?query=deployment&scope=team&team_id=<uuid>&hybrid=true

Response

Returns ranked memories with:

  • Combined score from vector + lexical signals
  • Temporal decay weighting (based on hnms_mode)
  • Relevance feedback adjustments (if enabled)
  • Provenance metadata for citations
get/api/v1/memories/search

Request

  • The document declares no server URL.
  • Auth: HTTP bearer

Query parameters

querystring required

Search query text

scopestring nullable

Filter by scope: personal, team, department, organization

team_idstring nullable

Filter by team ID (requires scope=team)

hybridboolean

Enable hybrid search (BM25 + vector similarity). When true, combines full-text lexical search with semantic vector search for better recall.

hnms_mode'balanced' | 'performance' | 'research'

HNMS-inspired ranking mode selector for search.

HNMS-inspired ranking mode: balanced (default), performance (prefer recent), research (prefer historical)

limitinteger

Maximum number of results to return

include_enrichmentboolean

Include facts_used and disputed_facts enrichment

include_playbooksboolean

Include playbook matches for this query

Headers

X-API-Keystring nullable

Response

Successful Response

trace_idstring nullable
querystring required
totalinteger required
took_msnumber required
ranking_metaobject nullable
facts_usedobject[] nullable
disputed_factsobject[] nullable
playbooksobject[] nullable

Changes

No recorded changes to this operation across all 2 revisions of this API.