Memories Endpoints

Memories are the core data units in zkstash. These endpoints allow you to store, retrieve, and manage the long-term memory of your agents.

Create Memory

Extracts and stores new memories from a conversation. The system automatically processes the conversation using your registered schemas to create structured memories.

Endpoint: POST /memories

Request Body

Field	Type	Required	Description
`agentId`	`string`	Yes	Unique identifier for the agent.
`conversation`	`array`	Yes	List of message objects representing the interaction.
`threadId`	`string`	No	Identifier for the conversation thread.
`schemas`	`string[]`	No	List of schema names to use for extraction. If omitted, uses all registered schemas.

Conversation Object:


{
  "role": "user" | "assistant" | "system",
  "content": "string"
}

Example Request


{
  "agentId": "agent-007",
  "conversation": [
    { "role": "user", "content": "My favorite color is blue." },
    { "role": "assistant", "content": "Noted." }
  ]
}

Response

Returns the created and updated memories.


{
  "success": true,
  "created": [
    {
      "kind": "UserProfile",
      "metadata": { "favoriteColor": "blue" }
    }
  ],
  "updated": []
}

Search Memories

Search for memories using semantic similarity and metadata filters.

Endpoint: GET /memories/search

Query Parameters

Parameter	Type	Required	Description
`query`	`string`	Yes	The natural language query to search for (e.g., “user preferences”).
`agentId`	`string`	No	Filter by agent ID.
`threadId`	`string`	No	Filter by specific thread ID.
`kind`	`string`	No	Filter by memory schema type (e.g., `UserProfile`).
`tags`	`string`	No	Comma-separated list of tags to filter by.
`limit`	`number`	No	Max number of results (default: 10).
`mode`	`string`	No	Response format: `raw` (default), `answer` (QA), or `map` (Graph).

Example Request


GET /memories/search?query=What+does+he+like?&agentId=agent-007&limit=5

Response


{
  "success": true,
  "memories": [
    {
      "id": "mem_123...",
      "kind": "UserProfile",
      "score": 0.89,
      "data": { "favoriteColor": "blue" },
      "metadata": {
        "agentId": "agent-007",
        "timestamp": 1700000000
      }
    }
  ]
}

Get Memory

Retrieve a single memory by its ID.

Endpoint: GET /memories/[id]

Parameters

Parameter	Type	Required	Description
`id`	`string`	Yes	The unique ID of the memory.

Response


{
  "success": true,
  "memory": {
    "id": "mem_123...",
    "kind": "UserProfile",
    "data": { ... }
  }
}

Update Memory

Update a memory’s metadata or extend its retention lease.

Endpoint: PATCH /memories/[id]

Request Body

Field	Type	Required	Description
`tags`	`string[]`	No	New list of tags for the memory.
`extendLease`	`boolean`	No	If `true`, resets the memory’s retention period (e.g., extends TTL by 7 days for free plans).

Example Request


{
  "tags": ["important", "verified"],
  "extendLease": true
}

Response


{
  "success": true,
  "memory": { ... }
}