Memory

Fold Memory provides vector-based storage for AI agents. Store embeddings, perform semantic search, and give your functions persistent memory — all scoped to your organization for full data isolation.

How it works

You can store raw vectors or plain text (which is automatically embedded). Query by text or vector to find semantically similar entries.

Each organization's vectors are isolated — you can only read and write your own data.

Storing memories (POST /vectors/upsert)

Store one or more vectors. Provide either text (auto-embedded) or values (raw vector):

curl -X POST https://api.fold.run/vectors/upsert \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "vectors": [
      {
        "id": "conv-001",
        "text": "User prefers dark mode and compact layouts",
        "metadata": { "type": "preference", "user": "alice" }
      },
      {
        "id": "conv-002",
        "text": "Project deadline is March 15th",
        "metadata": { "type": "fact", "user": "alice" }
      }
    ]
  }'

Field	Type	Required	Description
vectors	array	Yes	Up to 100 vectors per request
vectors[].id	string	Yes	Unique ID for this vector
vectors[].text	string	No	Plain text (auto-embedded)
vectors[].values	number[]	No	Raw embedding vector
vectors[].metadata	object	No	Arbitrary metadata for filtering
vectors[].namespace	string	No	Optional namespace for grouping

Provide either text or values — if both are given, text is embedded and values is ignored.

Querying memories (POST /vectors/query)

Search for semantically similar entries:

curl -X POST https://api.fold.run/vectors/query \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query_text": "What are the user preferences?",
    "top_k": 5
  }'

Response:

{
  "matches": [
    {
      "id": "conv-001",
      "score": 0.92,
      "metadata": { "type": "preference", "user": "alice" }
    }
  ],
  "count": 1
}

Field	Type	Required	Description
query_text	string	No	Text to search for (auto-embedded)
query_vector	number[]	No	Raw vector to search with
top_k	number	No	Number of results (default 10, max 100)
namespace	string	No	Filter by namespace
filter	object	No	Metadata filter

Deleting memories (POST /vectors/delete)

Remove vectors by their IDs:

curl -X POST https://api.fold.run/vectors/delete \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": ["conv-001", "conv-002"]
  }'

Use cases

• Agent memory — Store conversation context so your agent remembers past interactions.
• Knowledge base — Index documents and let your functions answer questions from them.
• Recommendations — Store user preferences and find similar items by semantic search.
• RAG (retrieval-augmented generation) — Query relevant context before generating responses.

Namespaces

Use the namespace field to isolate vectors by function or purpose:

curl -X POST https://api.fold.run/vectors/upsert \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "vectors": [
      {
        "id": "doc-1",
        "text": "Getting started with the API",
        "namespace": "help-docs"
      }
    ]
  }'

Then query only that namespace:

{
  "query_text": "how do I start?",
  "namespace": "help-docs",
  "top_k": 3
}

Limits

• Max 100 vectors per upsert request
• Max 100 results per query (top_k)
• Embedding model: bge-base-en-v1.5 (768 dimensions)
• Vectors are scoped and isolated per organization