MemNexus
Concepts

Semantic Search

How MemNexus finds memories by meaning using vector embeddings and hybrid search.

Traditional search matches keywords. Semantic search matches meaning. MemNexus combines both for the best results.

How it works

When you create a memory, MemNexus generates a vector embedding — a mathematical representation of the memory's meaning in 1024-dimensional space. When you search, your query is also embedded, and MemNexus finds memories whose vectors are closest to your query vector.

"that deployment issue last week"
         │
         ▼ Embed query
   [0.012, -0.034, 0.089, ...]  (1024 dimensions)
         │
         ▼ Cosine similarity
   Compare against all memory embeddings
         │
         ▼ Rank by similarity
   Semantic matches, one input to hybrid ranking

This means "that deployment issue" finds memories about deployments even if the memory doesn't contain the word "deployment" — because the meanings are close in vector space.

The embedding model

MemNexus uses a 1024-dimension embedding model to generate embeddings:

  • Dimensions: 1,024
  • Similarity metric: Cosine similarity
  • Index type: Vector index

Each memory's content is embedded once at creation time and stored alongside the memory node in the graph database. Query embeddings are generated at search time.

Pure semantic search is powerful but not perfect — it can miss exact keyword matches. Pure keyword search finds exact terms but misses meaning. MemNexus runs both and merges the results.

The pipeline

Search query
    │
    ├──→ Semantic search (vector similarity)
    │         └── Ranks by meaning
    │
    ├──→ Keyword search (full-text index)
    │         └── Ranks by term frequency
    │
    └──→ Reciprocal Rank Fusion (RRF)
              └── Merges and re-ranks results

The diagram shows two of the retrieval branches that the default hybrid search fuses.

The query is embedded, then compared against memory embeddings using cosine similarity via the vector index.

Good at: Finding conceptually related content Example: "infrastructure problems" matches memories about "server outages" and "database connection failures"

The query is matched against memory content using the full-text index (powered by Apache Lucene).

Good at: Exact matches, error codes, specific names Example: "ECONNREFUSED" finds memories containing that exact error string

Step 3: Reciprocal Rank Fusion

Results from the retrieval branches are combined using RRF. Each result gets a score based on its rank in each branch:

RRF_score = Σ (1 / (k + rank_i))

Where k is a constant (30 in the default hybrid search) and rank_i is the result's position in each search. The default hybrid search fuses several weighted retrieval branches, not only the two searches above, and multiplies each branch's contribution by that branch's weight. Results that rank high in several branches get the highest combined scores.

Why hybrid search matters

QuerySemantic onlyKeyword onlyHybrid
"that deployment issue"Finds related memoriesMisses if "deployment" isn't in contentBest of both
"ECONNREFUSED error"Finds error-related memoriesFinds exact matchesCombines precision and recall
"Node.js best practices"Finds conceptual matchesFinds exact mentionsComprehensive results

Similarity scores

Hybrid search results include a score from 0 to 1. The score is normalized across all candidates the search ranked, before results are trimmed to your limit: the best candidate scores 1.0 and the weakest scores 0.0, so the results you receive usually run from 1.0 down to a value above 0. If every candidate has the same fused score, every result scores 1.0. On later pages (offset > 0), or when a top memory is marked contradicted, the first result can score below 1.0. The score may also be null, so check for it before using it.

Because of this normalization, a score ranks results within one query. It does not measure absolute similarity, and you cannot compare scores across queries. The top result usually scores 1.0 even when it is only loosely related to the query.

Each hybrid result also includes vectorScore, the similarity score (0 to 1) from the semantic branch. It is 0 when the semantic branch did not match that memory. MemNexus publishes no recommended cutoff for it.

If the embedding service is unavailable, search falls back to keyword matching: the threshold is not applied, scores are keyword relevance scores rather than 0-to-1 similarity scores, and vectorScore is null. A searchMethod: "semantic" request also falls back to keyword matching, without the threshold, if the semantic query fails.

The threshold parameter defaults to 0.5. It sets the minimum similarity score (0 to 1) for searchMethod: "semantic". In that method, score is the similarity score itself and is not normalized within the result set. A threshold you set does not filter hybrid results.

Search tips

  • Natural language works best — Write queries like you'd describe the memory to a person
  • Be specific — "React state management with Redux" outperforms "state"
  • Use topic filters — Narrow results when you know the category
  • Combine with time filters — --recent 7d limits to recent memories
  • Try rephrasing — If initial results aren't great, rephrase the query