Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.openmem.blog/llms.txt

Use this file to discover all available pages before exploring further.

GET /memories/search returns a ranked list of memories that match a query string. Depending on the provider, the ranking is driven by vector similarity, keyword matching, or a hybrid of both. Each result includes a score field so you can threshold results by confidence.
This endpoint requires the vector_search or keyword_search capability to be supported by your provider. Call GET /capabilities first to confirm. If your provider does not support either, GET /memories with a scope or tag filter is the appropriate fallback.

​
Query parameters

​
q
string
required
The search query. The provider runs semantic and/or keyword matching against all memories for the given user_id.
​
user_id
string
required
Return only memories belonging to this user. Search is always scoped to a single user.
​
scope
string
Restrict results to memories whose scope starts with this prefix (e.g. coding matches coding/preferences and coding/tools).
​
limit
integer
default:"10"
Maximum number of results to return. Maximum is 100.
​
min_score
number
Minimum similarity score (0–1) for a result to be included. Results with a score below this threshold are filtered out before the response is returned. Omit to return all results up to limit.

​
Response — 200 OK

​
results
SearchResult[]
required
Ranked list of matching memories, highest score first.

​
Example

curl "http://localhost:8080/memories/search?q=package+manager&user_id=u1&limit=5"

{
  "results": [
    {
      "memory": {
        "id": "mem_abc123",
        "content": "User prefers pnpm over npm",
        "user_id": "u1",
        "scope": "coding/preferences",
        "tags": ["tooling", "nodejs"],
        "confidence": 0.92,
        "created_at": "2026-04-27T10:00:00Z",
        "updated_at": "2026-04-27T10:00:00Z",
        "status": "done"
      },
      "score": 0.94
    },
    {
      "memory": {
        "id": "mem_def456",
        "content": "User has used yarn in legacy projects",
        "user_id": "u1",
        "scope": "coding/preferences",
        "tags": ["tooling"],
        "confidence": 0.75,
        "created_at": "2026-03-10T09:00:00Z",
        "updated_at": "2026-03-10T09:00:00Z",
        "status": "done"
      },
      "score": 0.71
    }
  ]
}

​
Filtering by minimum score

curl "http://localhost:8080/memories/search?q=package+manager&user_id=u1&min_score=0.8"
Only results with a similarity score of 0.8 or above are returned — useful when you want high-confidence matches for LLM prompt injection.