Search Memories

curl -X POST 'https://app.memorylake.ai/openapi/memorylake/api/v3/workspaces/ws-8001856949ad4f6a5b6226f415ffa877/memories/search' \
  -H 'Authorization: Bearer sk_xxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "What were the quarterly revenue figures?",
    "project_ids": ["proj-b93e8d95a8705bcc4ec42a65ba4cc7f8"],
    "memory_types": ["document", "fact"],
    "top_k": 10
  }'

{
  "success": true,
  "data": {
    "documents": [
      {
        "document_id": "doc-8ef7fb1915709b68aa2e8628f0fb9aab",
        "project_id": "proj-b93e8d95a8705bcc4ec42a65ba4cc7f8",
        "document_name": "Q1 2024 Financial Report",
        "file_name": "q1_2024_report.pdf",
        "document_summary": "Quarterly financial report covering revenue, expenses, and projections for Q1 2024.",
        "source_type": "upload",
        "sheet_name": null,
        "items": [
          {
            "text": "Q1 2024 revenue reached $12.5M, a 15% increase over Q4 2023.",
            "range": "p8"
          }
        ]
      }
    ],
    "facts": [
      {
        "id": "fact-bd3fcc4661d8942d0f84fb633de5cc59",
        "fact": "Company quarterly revenue for Q1 2024 was $12.5M",
        "score": 0.92,
        "metadata": {},
        "created_at": "2024-04-01T09:00:00Z",
        "updated_at": "2024-04-01T09:00:00Z",
        "owner": {
          "type": "project",
          "id": "proj-b93e8d95a8705bcc4ec42a65ba4cc7f8"
        }
      }
    ]
  }
}

curl -X POST 'https://app.memorylake.ai/openapi/memorylake/api/v3/workspaces/ws-8001856949ad4f6a5b6226f415ffa877/memories/search' \
  -H 'Authorization: Bearer sk_xxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "What were the quarterly revenue figures?",
    "project_ids": ["proj-b93e8d95a8705bcc4ec42a65ba4cc7f8"],
    "memory_types": ["document", "fact"],
    "top_k": 10
  }'

{
  "success": true,
  "data": {
    "documents": [
      {
        "document_id": "doc-8ef7fb1915709b68aa2e8628f0fb9aab",
        "project_id": "proj-b93e8d95a8705bcc4ec42a65ba4cc7f8",
        "document_name": "Q1 2024 Financial Report",
        "file_name": "q1_2024_report.pdf",
        "document_summary": "Quarterly financial report covering revenue, expenses, and projections for Q1 2024.",
        "source_type": "upload",
        "sheet_name": null,
        "items": [
          {
            "text": "Q1 2024 revenue reached $12.5M, a 15% increase over Q4 2023.",
            "range": "p8"
          }
        ]
      }
    ],
    "facts": [
      {
        "id": "fact-bd3fcc4661d8942d0f84fb633de5cc59",
        "fact": "Company quarterly revenue for Q1 2024 was $12.5M",
        "score": 0.92,
        "metadata": {},
        "created_at": "2024-04-01T09:00:00Z",
        "updated_at": "2024-04-01T09:00:00Z",
        "owner": {
          "type": "project",
          "id": "proj-b93e8d95a8705bcc4ec42a65ba4cc7f8"
        }
      }
    ]
  }
}

POST /openapi/memorylake/api/v3/workspaces/{workspaceId}/memories/search

Searches across all memory sources in a workspace — documents and facts — using a natural language query. Results are grouped by source type so you can present each category separately or merge them in your UI. Documents are searched only in the projects you list in project_ids; the other optional filters choose actors, agents, or memory types.

Permission required: workspace:memory_search on the workspace, plus one per thing you name — on each project in project_ids: project:mem_search and project:doc_search; on each actor in actor_ids: workspace_actor:fact_search; on each agent in agent_ids: workspace_agent:fact_search. Naming something you may not search refuses the whole request.

Path Parameters

string

required

Workspace identifier

Request Body

string

required

Natural language search query

array of strings

Projects to search. Documents are searched only in the projects listed here: when omitted, no project is searched and documents comes back empty. Facts are still searched for the actors and agents in the request, or for your own actor when neither actor_ids nor agent_ids is set.

array of strings

Limit search to memories associated with specific actors

array of strings

Limit search to memories belonging to specific agents.

array of strings

Filter results by memory type. Accepted values: document, fact. When omitted, all types are searched.

integer

default:"10"

Maximum number of results to return in total (1–1000). One budget is shared by all searched memory types, not a limit per type: top_k=5 may come back as five documents, or as three documents and two facts, depending only on what best answers the query. Fewer results may be returned.

string

How thoroughly to search, trading result quality for speed:

max — run the full search.
high — do not expand the query from stored facts, and use a lighter final ranking. Typically answers noticeably faster than max.
low — like high, and also skip model-based understanding of the query and narrow recall, for the fastest answers.

Lower levels may return fewer or different results for the same query. When omitted, the default level applies. Any other value returns 400.

curl -X POST 'https://app.memorylake.ai/openapi/memorylake/api/v3/workspaces/ws-8001856949ad4f6a5b6226f415ffa877/memories/search' \
  -H 'Authorization: Bearer sk_xxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "What were the quarterly revenue figures?",
    "project_ids": ["proj-b93e8d95a8705bcc4ec42a65ba4cc7f8"],
    "memory_types": ["document", "fact"],
    "top_k": 10
  }'

Response

object

Show Search results grouped by source type

array

Document search results, grouped by source document

Show DocumentSearchResult

string

Document identifier

string

ID of the project this document belongs to, always one of the project_ids you sent. Use it with document_id to address the document afterwards, e.g. to get or download it.

string

Display name of the document

string

Original file name

string

Summary of the document

string

Source type of the document (e.g. upload, connector)

string

Worksheet name, if the document is a workbook

array

Matched content items within the document

array

Fact search results

Show FactSearchResult

string

Fact identifier

string

The fact text

number

Relevance score

object

Additional metadata associated with the fact

string

Creation timestamp

string

Last update timestamp

object

The project, actor or agent this fact belongs to, reported by the ID the request used for it. When the request sets neither actor_ids nor agent_ids, your own actor is searched too — even if project_ids is set — and its facts are reported as that actor. Use it to address the fact afterwards, e.g. to read it; updating or deleting a fact also requires its owner to still exist.

Show Owner object

string

Owner type: project, actor or agent

string

Owner ID: a project ID when type is project, an actor ID when type is actor, an agent ID when type is agent

{
  "success": true,
  "data": {
    "documents": [
      {
        "document_id": "doc-8ef7fb1915709b68aa2e8628f0fb9aab",
        "project_id": "proj-b93e8d95a8705bcc4ec42a65ba4cc7f8",
        "document_name": "Q1 2024 Financial Report",
        "file_name": "q1_2024_report.pdf",
        "document_summary": "Quarterly financial report covering revenue, expenses, and projections for Q1 2024.",
        "source_type": "upload",
        "sheet_name": null,
        "items": [
          {
            "text": "Q1 2024 revenue reached $12.5M, a 15% increase over Q4 2023.",
            "range": "p8"
          }
        ]
      }
    ],
    "facts": [
      {
        "id": "fact-bd3fcc4661d8942d0f84fb633de5cc59",
        "fact": "Company quarterly revenue for Q1 2024 was $12.5M",
        "score": 0.92,
        "metadata": {},
        "created_at": "2024-04-01T09:00:00Z",
        "updated_at": "2024-04-01T09:00:00Z",
        "owner": {
          "type": "project",
          "id": "proj-b93e8d95a8705bcc4ec42a65ba4cc7f8"
        }
      }
    ]
  }
}

MemoryLake API

Memory Router API

Path Parameters

Request Body

Response

​Path Parameters

​Request Body

​Response

Path Parameters

Request Body

Response