Search API

Run semantic and keyword search across your workspace memories. The search endpoint runs keyword, semantic (pgvector cosine similarity), and graph lookups, merges them, and orders the merged candidates by relevance. Use it to surface relevant past decisions, patterns, and context before starting new work.

See Memory Concepts for how memories are structured, or Knowledge Base Ingestion cookbook for bulk ingestion patterns.

Base URL and Authentication

https://api.neuroloom.dev

All requests require an API key:

Authorization: Token $MEMORIES_API_TOKEN

Search Memories

POST /api/v1/memories/search

Combined keyword, semantic, and graph search. Results are returned ordered by score descending.

How Ranking Works

A search runs in three steps:

1. Retrieve. Keyword (full-text), semantic (vector similarity), and graph lookups each produce a ranked list of candidate memories.
2. Fuse. Reciprocal rank fusion (RRF) merges the lists. RRF is a rank-based method: each list gives a memory 1 / (60 + rank) points, so a memory that several lists agree on rises above one found by a single list. An RRF score is small: a top hit found by one list scores about 0.016, and one found by all three about 0.05.
3. Rerank. On paid plans, the top 50 fused candidates go to a cross-encoder reranker, a model that reads the query and one memory together and outputs a relevance probability between 0 and 1. Results are sorted by that relevance.

When reranking runs, stored importance_score and confidence_score do not change the order. Two small adjustments apply on top of the reranker's relevance: a memory that a newer memory supersedes is scaled by 0.7, and the recency search profile scales each result by up to ±5% depending on age. Use min_importance and min_confidence when you want to filter on those fields instead.

Reranking does not run on the Free plan, and it is skipped when the reranker is unavailable (see degradation_reason below). In those responses rerank_score is null and score is the RRF score, which is not comparable to a reranked score. See Reading scores.

Semantic search uses precomputed embeddings and requires an embedding provider to be configured. If none is configured, the endpoint falls back to keyword-only ranking.

memory_search(
  query="database connection pooling strategy",
  memory_types=["pattern", "decision"],
  min_importance=0.6,
  limit=10
)

memory_by_file(
  file_path="api/neuroloom_api/routers/memories.py",
  limit=10
)

import httpx, os

response = httpx.post(
    "https://api.neuroloom.dev/api/v1/memories/search",
    headers={"Authorization": f"Token {os.environ['MEMORIES_API_TOKEN']}"},
    json={
        "query": "database connection pooling strategy",
        "memory_types": ["pattern", "decision"],
        "min_importance": 0.6,
        "limit": 10,
        "use_semantic": True,
    },
)
results = response.json()
for r in results["results"]:
    print(r["memory"]["title"], r["score"])

curl -X POST "https://api.neuroloom.dev/api/v1/memories/search" \
  -H "Authorization: Token $MEMORIES_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "database connection pooling strategy",
    "memory_types": ["pattern", "decision"],
    "min_importance": 0.6,
    "limit": 10
  }'

Request Body

Response

200 OK

{
  "count": 2,
  "query": "database connection pooling strategy",
  "filters": {
    "workspace_id": "ws-xyz789",
    "memory_types": ["pattern", "decision"],
    "tags": null,
    "tags_match": "any",
    "min_importance": 0.6
  },
  "results": [
    {
      "memory": {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "workspace_id": "ws-xyz789",
        "title": "Use connection pooling for all DB connections",
        "narrative": "Configure SQLAlchemy with pool_size=10, max_overflow=20. Never create engines per-request — share a single engine per process.",
        "memory_type": "pattern",
        "tags": ["sqlalchemy", "database", "performance"],
        "concepts": ["connection-pooling", "database"],
        "source_files": ["api/neuroloom_api/database.py"],
        "importance_score": 0.88,
        "confidence_score": 0.9,
        "content_hash": null,
        "pagerank_score": 0.45,
        "community_label": "database-patterns",
        "access_count": 8,
        "retrieval_count": 22,
        "created_at": "2026-03-15T10:00:00Z"
      },
      "score": 0.96,
      "keyword_score": 0.0,
      "semantic_score": 0.0,
      "match_type": "combined",
      "rrf_score": 0.0325,
      "rerank_score": 0.96,
      "low_confidence": false
    }
  ],
  "degraded": false,
  "degradation_reason": null,
  "code_graph_available": true
}

Top-level response fields

SearchResult fields

Full-memory responses also carry matched_fields, snippet, supersession_trail, and lineage on each result.

Reading scores

score and rerank_score mean different things depending on whether the response was reranked. Check rerank_score first.

On the Free plan the response is unreranked by design and degraded stays false. When a paid-plan reranker failure forces the fallback, degraded is true and degradation_reason is "reranker_error". A response is either fully reranked or fully unreranked. Candidates the reranker did not score are dropped from a reranked response instead of being appended after the scored ones.

Reranker scores cluster at the extremes. On Neuroloom's own evaluation corpus (hybrid search), memories judged relevant to a query had a median rerank_score of about 0.97 with most above 0.9, and unrelated memories had a median of about 0.0005 with 75% below 0.007. The distribution is close to bimodal, so few results land in a "maybe" middle. Your corpus and queries will differ; treat these as a starting point, not a guarantee.

min_score gates rerank_score, not score, so a result can pass min_score and still show a lower score. A superseded memory with rerank_score: 0.06 has score: 0.042 and passes min_score: 0.05.

Pagination and the 50-result cap

offset skips candidates in the fused (pre-rerank) order, then the reranker scores the next 50 and the response returns the top limit of them. Two consequences:

• A reranked response never holds more than 50 results, whatever limit is. Set limit above 50 and you still get at most 50.
• Each page is reranked independently, so a memory can appear on two pages or on neither. Don't rely on offset for a stable walk through every match; use narrower filters or a larger limit (up to 50) instead.

An unreranked response has no 50-result cap; limit applies as written.

Batch Search

POST /api/v1/memories/search/batch

Run several queries in one request. The server embeds all queries in one call and searches them concurrently, which is faster than N separate requests.

curl -X POST "https://api.neuroloom.dev/api/v1/memories/search/batch" \
  -H "Authorization: Token $MEMORIES_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "queries": [
      "database connection pooling strategy",
      "async session configuration"
    ],
    "limit": 5,
    "min_score": 0.05
  }'

The response always returns 200 OK with one entry per query, in request order. Each result has the same shape as a single-search result (the example below abbreviates the memory object). A failed query has success: false, results: null, and an error string such as "query_timeout" or "batch_timeout"; the other queries still return results.

{
  "batch_size": 2,
  "success_count": 2,
  "failure_count": 0,
  "results": [
    {
      "query_index": 0,
      "query": "database connection pooling strategy",
      "success": true,
      "results": [ { "memory": { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "title": "Use connection pooling for all DB connections" }, "score": 0.96, "rerank_score": 0.96, "rrf_score": 0.0325 } ],
      "error": null
    }
  ]
}

Common Search Patterns

Find memories by file

Surface decisions and patterns captured while working on a specific file. query is required — pair the files filter with a real query describing what you're looking for in that file, rather than leaving it empty:

curl -X POST "https://api.neuroloom.dev/api/v1/memories/search" \
  -H "Authorization: Token $MEMORIES_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "routing and search endpoint changes",
    "files": ["api/neuroloom_api/routers/memories.py"],
    "limit": 20
  }'

Keyword-only search

Disable semantic ranking for exact phrase matching:

curl -X POST "https://api.neuroloom.dev/api/v1/memories/search" \
  -H "Authorization: Token $MEMORIES_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "HNSW ef_construction",
    "use_semantic": false,
    "limit": 10
  }'

High-importance decisions only

Retrieve only well-established decisions above an importance threshold:

curl -X POST "https://api.neuroloom.dev/api/v1/memories/search" \
  -H "Authorization: Token $MEMORIES_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "database schema migration strategy",
    "memory_types": ["decision", "architecture"],
    "min_importance": 0.8,
    "limit": 5
  }'

Filter by tags

Narrow a search to memories tagged with specific labels. By default a memory needs any one of the tags:

curl -X POST "https://api.neuroloom.dev/api/v1/memories/search" \
  -H "Authorization: Token $MEMORIES_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "HNSW index tuning",
    "tags": ["pgvector", "performance"],
    "limit": 20
  }'

Set tags_match to "all" to require every tag:

curl -X POST "https://api.neuroloom.dev/api/v1/memories/search" \
  -H "Authorization: Token $MEMORIES_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "HNSW index tuning",
    "tags": ["pgvector", "performance"],
    "tags_match": "all",
    "limit": 20
  }'

Semantic Search Fallback

When semantic search is enabled (use_semantic: true) but embeddings are unavailable — either because no embedding provider API key is configured or because a memory's embedding has not yet been generated — the endpoint falls back to keyword-only ranking. Results are still returned; only the scoring changes.

To check whether a memory has an embedding, inspect whether pagerank_score is non-null (both are populated by the same background job). Embeddings are generated asynchronously after memory creation, typically within seconds.

Error Responses

{
  "detail": [
    {
      "loc": ["body", "limit"],
      "msg": "Input should be less than or equal to 200",
      "type": "less_than_equal"
    }
  ]
}

A whitespace-only query returns:

{
  "detail": [
    {
      "loc": ["body", "query"],
      "msg": "Value error, query must not be empty or whitespace-only. Use GET /memories/ for filter-only browsing.",
      "type": "value_error"
    }
  ]
}

Related

• What is a Memory — memory types, fields, and data model
• Memory Lifecycle — how importance scores affect search ranking
• Knowledge Base Ingestion — bulk ingestion patterns for semantic search