Collections

Collections provide a lightweight key-value store with vector similarity search. Use collections to manage reusable content such as prompt templates, tool definitions, knowledge base entries, or any items that benefit from semantic retrieval.

Create a Collection Item

curl -X POST "$MEMORYLAYER_URL/v1/collections" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "collection_name": "prompts",
    "name": "summarize-email",
    "content": "Summarize the following email thread into 3 bullet points...",
    "item_type": "prompt_template",
    "tags": ["email", "summarization"],
    "metadata": {"version": "1.2"},
    "enabled": true
  }'

Fields:

Field	Required	Description
`collection_name`	Yes	Logical grouping name
`name`	Yes	Item name (unique within collection recommended)
`content`	Yes	Item content (text)
`item_type`	No	Free-form type label
`tags`	No	List of string tags
`metadata`	No	Arbitrary key-value metadata
`enabled`	No	Whether the item is active (default `true`)

List Items

# All items across collections
curl "$MEMORYLAYER_URL/v1/collections?limit=50&offset=0" \
  -H "Authorization: Bearer $API_KEY"

# Filter by collection name
curl "$MEMORYLAYER_URL/v1/collections?collection_name=prompts" \
  -H "Authorization: Bearer $API_KEY"

Get a Single Item

curl "$MEMORYLAYER_URL/v1/collections/$ITEM_ID" \
  -H "Authorization: Bearer $API_KEY"

Update an Item

Only provided fields are updated; others remain unchanged.

curl -X PUT "$MEMORYLAYER_URL/v1/collections/$ITEM_ID" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Updated prompt template text...",
    "tags": ["email", "summarization", "v2"]
  }'

Delete an Item

curl -X DELETE "$MEMORYLAYER_URL/v1/collections/$ITEM_ID" \
  -H "Authorization: Bearer $API_KEY"

Similarity Search

Search collection items by vector similarity. Provide a pre-computed embedding vector as the query.

curl -X POST "$MEMORYLAYER_URL/v1/collections/search" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query_embedding": [0.12, -0.45, 0.78, ...],
    "collection_name": "prompts",
    "limit": 5
  }'

Search parameters:

Field	Required	Description
`query_embedding`	Yes	Query embedding vector (must match collection dimension)
`collection_name`	No	Filter search to a specific collection
`limit`	No	Maximum results to return (1—100, default 10)

Response includes items ranked by similarity score:

{
  "results": [
    {
      "item": {
        "id": "col_abc123",
        "collection_name": "prompts",
        "name": "summarize-email",
        "content": "Summarize the following email thread...",
        "tags": ["email", "summarization"],
        "enabled": true,
        "created_at": "2026-04-01T12:00:00Z",
        "updated_at": "2026-04-01T12:00:00Z"
      },
      "similarity": 0.92
    }
  ],
  "total_count": 1
}

Use Cases

Use Case	Collection Name	Description
Prompt library	`prompts`	Store and retrieve prompt templates by semantic similarity
Tool registry	`tools`	Register tool definitions for agent function calling
Knowledge base	`kb-articles`	Searchable knowledge base entries
FAQ	`faq`	Frequently asked questions with semantic lookup
Code snippets	`snippets`	Reusable code patterns searchable by description