agent-swarm.devagent-swarm.dev

Memory

Search, retrieve, and manage persistent agent memories across sessions

DELETE
/api/memory/{id}

Authorization

bearerAuth
AuthorizationBearer <token>

API key via Authorization: Bearer <API_KEY>

In: header

Path Parameters

id*string
Formatuuid

Response Body

application/json

application/json

curl -X DELETE "http://localhost:3013/api/memory/497f6eca-6276-4993-bfeb-53cbbbba6f08"
{
  "deleted": true
}
{
  "error": "string",
  "property1": null,
  "property2": null
}
GET
/api/memory/{id}

Authorization

bearerAuth
AuthorizationBearer <token>

API key via Authorization: Bearer <API_KEY>

In: header

Path Parameters

id*string
Formatuuid

Query Parameters

intent?string

Why you are retrieving this memory. Required for agent recall-edge tracking; omit for UI browse calls.

Length1 <= length

Response Body

application/json

application/json

curl -X GET "http://localhost:3013/api/memory/497f6eca-6276-4993-bfeb-53cbbbba6f08"
{
  "memory": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "agentId": "string",
    "scope": "agent",
    "key": "string",
    "name": "string",
    "content": "string",
    "summary": "string",
    "source": "manual",
    "sourceTaskId": "b46343f0-19a2-4701-a438-6edf056909b2",
    "sourcePath": "string",
    "chunkIndex": 0,
    "totalChunks": 1,
    "tags": [
      "string"
    ],
    "createdAt": "string",
    "updatedAt": "string",
    "accessedAt": "string",
    "expiresAt": "string",
    "accessCount": 0,
    "embeddingModel": "string",
    "contentHash": "string",
    "version": 1
  },
  "links": [
    {
      "id": "string",
      "linkType": "wikilink",
      "targetKind": "memory",
      "targetId": "string",
      "strength": 0,
      "resolver": "string",
      "sourceText": "string",
      "createdAt": "string",
      "resolved": true,
      "target": {
        "id": "string",
        "name": "string",
        "scope": "string"
      }
    }
  ],
  "backlinks": [
    {
      "id": "string",
      "linkType": "wikilink",
      "strength": 0,
      "sourceText": "string",
      "createdAt": "string",
      "from": {
        "id": "string",
        "name": "string",
        "scope": "string"
      }
    }
  ]
}
{
  "error": "string",
  "property1": null,
  "property2": null
}
GET
/api/memory/edges

Authorization

bearerAuth
AuthorizationBearer <token>

API key via Authorization: Bearer <API_KEY>

In: header

Query Parameters

memoryId*string
Length1 <= length

Response Body

application/json

application/json

curl -X GET "http://localhost:3013/api/memory/edges?memoryId=string"
{
  "edges": [
    {
      "to": "string",
      "type": "references-source",
      "alpha": 0,
      "beta": 0,
      "usefulness": 0,
      "createdAt": "string"
    }
  ]
}
{
  "error": "string",
  "property1": null,
  "property2": null
}
POST
/api/memory/edit

Authorization

bearerAuth
AuthorizationBearer <token>

API key via Authorization: Bearer <API_KEY>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

curl -X POST "http://localhost:3013/api/memory/edit" \  -H "Content-Type: application/json" \  -d '{    "intent": "string"  }'
{
  "memory": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "agentId": "string",
    "scope": "agent",
    "key": "string",
    "name": "string",
    "content": "string",
    "summary": "string",
    "source": "manual",
    "sourceTaskId": "b46343f0-19a2-4701-a438-6edf056909b2",
    "sourcePath": "string",
    "chunkIndex": 0,
    "totalChunks": 1,
    "tags": [
      "string"
    ],
    "createdAt": "string",
    "updatedAt": "string",
    "accessedAt": "string",
    "expiresAt": "string",
    "accessCount": 0,
    "embeddingModel": "string",
    "contentHash": "string",
    "version": 1
  },
  "changed": true,
  "previousVersion": 0,
  "version": 0,
  "contentHash": "string"
}
{
  "error": "string",
  "property1": null,
  "property2": null
}
{
  "error": "string",
  "property1": null,
  "property2": null
}
{
  "error": "string",
  "property1": null,
  "property2": null
}
GET
/api/memory/health

Authorization

bearerAuth
AuthorizationBearer <token>

API key via Authorization: Bearer <API_KEY>

In: header

Response Body

application/json

curl -X GET "http://localhost:3013/api/memory/health"
{
  "sqliteVec": {
    "extensionLoaded": true,
    "tableExists": true,
    "initialized": true,
    "vectorDimensions": 0,
    "distanceMetric": "cosine",
    "schema": "string",
    "lastPopulate": {
      "attempted": 0,
      "inserted": 0,
      "skippedInvalidDimensions": 0,
      "failed": 0,
      "beforeCount": 0,
      "afterCount": 0
    }
  },
  "counts": {
    "total": 0,
    "withEmbedding": 0,
    "validEmbedding": 0,
    "invalidEmbedding": 0,
    "searchable": 0,
    "memoryVec": 0,
    "missingFromVec": 0,
    "extraInVec": 0
  },
  "retrievalMode": "vec",
  "reasons": [
    "string"
  ]
}
POST
/api/memory/index

Authorization

bearerAuth
AuthorizationBearer <token>

API key via Authorization: Bearer <API_KEY>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

curl -X POST "http://localhost:3013/api/memory/index" \  -H "Content-Type: application/json" \  -d '{    "content": "string",    "name": "string",    "scope": "agent",    "source": "manual"  }'
{
  "queued": true,
  "memoryIds": [
    "string"
  ],
  "skipped": "string",
  "edited": true
}
{
  "error": "string",
  "property1": null,
  "property2": null
}
POST
/api/memory/list

Authorization

bearerAuth
AuthorizationBearer <token>

API key via Authorization: Bearer <API_KEY>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

curl -X POST "http://localhost:3013/api/memory/list" \  -H "Content-Type: application/json" \  -d '{}'
{
  "results": [
    {
      "id": "string",
      "name": "string",
      "content": "string",
      "agentId": "string",
      "scope": "agent",
      "source": "manual",
      "similarity": 0,
      "rawSimilarity": 0,
      "compositeScore": 0,
      "retrievalSource": "vec",
      "createdAt": "string",
      "accessedAt": "string",
      "accessCount": 0,
      "expiresAt": "string",
      "embeddingModel": "string",
      "sourceTaskId": "string",
      "sourcePath": "string",
      "chunkIndex": 0,
      "totalChunks": 0,
      "tags": [
        "string"
      ]
    }
  ],
  "total": 0,
  "limit": 0,
  "offset": 0,
  "mode": "semantic"
}
{
  "error": "string",
  "property1": null,
  "property2": null
}
POST
/api/memory/rate

Authorization

bearerAuth
AuthorizationBearer <token>

API key via Authorization: Bearer <API_KEY>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

curl -X POST "http://localhost:3013/api/memory/rate" \  -H "Content-Type: application/json" \  -d '{    "events": [      {        "memoryId": "string",        "signal": -1,        "weight": 1,        "source": "llm"      }    ]  }'
{
  "applied": 0,
  "rejected": [
    {
      "memoryId": "string",
      "reason": "string"
    }
  ]
}
{
  "error": "string",
  "property1": null,
  "property2": null
}
{
  "error": "string",
  "property1": null,
  "property2": null
}
POST
/api/memory/re-embed

Authorization

bearerAuth
AuthorizationBearer <token>

API key via Authorization: Bearer <API_KEY>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

curl -X POST "http://localhost:3013/api/memory/re-embed" \  -H "Content-Type: application/json" \  -d '{}'
{
  "started": true,
  "totalMemories": 0
}
GET
/api/memory/retrievals

Authorization

bearerAuth
AuthorizationBearer <token>

API key via Authorization: Bearer <API_KEY>

In: header

Query Parameters

taskId?string
Formatuuid
sessionId?string

Response Body

application/json

application/json

curl -X GET "http://localhost:3013/api/memory/retrievals"
{
  "results": [
    {
      "id": "string",
      "name": "string",
      "content": "string",
      "scope": "string",
      "source": "string",
      "scheduleId": "string",
      "similarity": 0,
      "retrievalSource": "string",
      "retrievedAt": "string"
    }
  ]
}
{
  "error": "string",
  "property1": null,
  "property2": null
}
POST
/api/memory/search

Authorization

bearerAuth
AuthorizationBearer <token>

API key via Authorization: Bearer <API_KEY>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

curl -X POST "http://localhost:3013/api/memory/search" \  -H "Content-Type: application/json" \  -d '{    "query": "string"  }'
{
  "results": [
    {
      "id": "string",
      "name": "string",
      "content": "string",
      "similarity": 0,
      "rawSimilarity": 0,
      "compositeScore": 0,
      "retrievalSource": "vec",
      "source": "manual",
      "scope": "agent",
      "tags": [
        "string"
      ]
    }
  ]
}
{
  "error": "string",
  "property1": null,
  "property2": null
}
GET
/api/memory/usefulness

Authorization

bearerAuth
AuthorizationBearer <token>

API key via Authorization: Bearer <API_KEY>

In: header

Query Parameters

days?integer

Analysis window in days (default 30)

Default30
Range1 <= value <= 365
threshold?|

Posterior-mean threshold for the aboveThreshold count (default 0.6)

Default0.6
Range0 <= value <= 1

Response Body

application/json

application/json

curl -X GET "http://localhost:3013/api/memory/usefulness"
{
  "windowDays": 0,
  "threshold": 0,
  "cutoff": "string",
  "volume": {
    "retrievals": 0,
    "distinctMemories": 0,
    "retrievalGroups": 0,
    "byEventType": {
      "search": 0,
      "get": 0
    }
  },
  "byArm": [
    {
      "retrievalSource": "string",
      "retrievals": 0,
      "distinctMemories": 0,
      "citedRetrievals": 0,
      "citationRate": 0
    }
  ],
  "citationBySource": [
    {
      "source": "string",
      "ratings": 0,
      "positive": 0,
      "citationRate": 0,
      "avgSignal": 0
    }
  ],
  "posterior": {
    "totalMemories": 0,
    "movedFromPrior": 0,
    "avgPosteriorMean": 0,
    "avgPosteriorMeanMoved": 0,
    "aboveThreshold": 0
  },
  "sanity": {
    "totalRetrievalRows": 0,
    "totalRatingRows": 0,
    "ratingsBySource": [
      {
        "source": "string",
        "count": 0
      }
    ]
  }
}
{
  "error": "string",
  "property1": null,
  "property2": null
}

MCP Servers

Register and manage MCP tool servers available to swarm agents

Metrics

Metrics API endpoints