New

CRUD Operations

Create, read, update, and delete memory facts programmatically.

POSTCreate Fact

Create a new memory fact.

bash

POST /api/memory/facts

Request Body

json

{
  "content": "User prefers dark mode",
  "category": "preference",    // optional
  "source": "api",             // "api" | "explicit_command" | "auto_detected"
  "level": "user"              // "user" | "session"
}

Response

json

{
  "success": true,
  "data": {
    "id": "fact-uuid-123",
    "userId": "user-123",
    "content": "User prefers dark mode",
    "category": "preference",
    "source": "api",
    "level": "user",
    "vectorId": "vec-123",
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:30:00Z",
    "accessCount": 0
  }
}

Example

create-fact.ts

const response = await fetch('https://www.superagentstack.com/api/memory/facts', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'superAgentKey': process.env.SUPER_AGENT_KEY,
  },
  body: JSON.stringify({
    content: 'User prefers dark mode',
    category: 'preference',
    level: 'user',
  }),
});

const { data: fact } = await response.json();
console.log('Created fact:', fact.id);

GETList Facts

List all memory facts with pagination.

bash

GET /api/memory/facts?limit=10&offset=0&category=preference

Query Parameters

Parameter	Type	Default	Description
limit	number	20	Max facts to return
offset	number	0	Pagination offset
category	string	-	Filter by category
level	string	-	Filter by level

Response

json

{
  "success": true,
  "data": [
    { "id": "fact-1", "content": "...", ... },
    { "id": "fact-2", "content": "...", ... }
  ],
  "pagination": {
    "total": 42,
    "limit": 10,
    "offset": 0,
    "hasMore": true
  }
}

POSTSearch Facts

Semantic search across memory facts.

bash

POST /api/memory/facts/search

Request Body

json

{
  "query": "programming preferences",
  "topK": 5,           // Max results
  "threshold": 0.7     // Min similarity score (0-1)
}

Response

json

{
  "success": true,
  "data": [
    {
      "id": "fact-1",
      "content": "User prefers TypeScript",
      "score": 0.92,
      ...
    }
  ]
}

PUTUpdate Fact

Update an existing memory fact.

bash

PUT /api/memory/facts/:id

Request Body

json

{
  "content": "User now prefers light mode",
  "category": "preference"
}

Re-embedding

When you update the content, the fact is automatically re-embedded for accurate semantic search.

DELETEDelete Fact

Permanently delete a memory fact.

bash

DELETE /api/memory/facts/:id

Response

json

{
  "success": true,
  "message": "Fact deleted successfully"
}

Permanent Deletion

Deleted facts cannot be recovered. The associated vector embedding is also removed.

Error Codes

Code	HTTP	Description
UNAUTHORIZED	401	Invalid or missing API key
NOT_FOUND	404	Fact not found
VALIDATION_ERROR	400	Invalid request body
RATE_LIMITED	429	Too many requests