Stan Memories

Manage long-term memories Stan retains about the current user. Memories are typed (preference, fact, context, instruction), carry an importance weighting, and are ranked at recall time using a decay score that combines importance, recency, and access frequency.

All endpoints require authentication via X-API-Key header and the appropriate scope.

---

Memory Object

{
  "_id": "mem_abc123",
  "type": "preference",
  "content": "Prefers terse, bullet-pointed responses.",
  "importance": 0.8,
  "score": 0.72,
  "source": "manual",
  "createdAt": "2025-02-10T12:00:00Z",
  "lastAccessedAt": "2025-02-15T09:30:00Z",
  "accessCount": 4
}

---

GET /api/v1/stan/memories

List all memories for the current user, ranked by decay score (descending).

Scope: stan:execute

Query Parameters

Parameter	Type	Required	Description
type	string	No	Filter by memory type: preference, fact, context, instruction
limit	integer	No	Max results per page (default: 50, max: 200)
cursor	string	No	meta.nextCursor of the previous page; omit for the first page

Response 200 OK

{
  "data": [
    {
      "_id": "mem_abc123",
      "type": "preference",
      "content": "Prefers terse, bullet-pointed responses.",
      "importance": 0.8,
      "score": 0.72,
      "source": "manual",
      "createdAt": "2025-02-10T12:00:00Z",
      "lastAccessedAt": "2025-02-15T09:30:00Z",
      "accessCount": 4
    }
  ],
  "meta": {
    "total": 12,
    "limit": 50,
    "nextCursor": null,
    "requestId": "req_abc123"
  }
}

---

POST /api/v1/stan/memories

Save a new memory about the current user.

Scope: stan:execute

Request Body

{
  "content": "Prefers terse, bullet-pointed responses.",
  "type": "preference",
  "importance": 0.8
}

Field	Type	Required	Description
content	string	Yes	The memory content to save
type	string	Yes	Memory type: preference, fact, context, instruction
importance	number	No	Importance score 0–1 (default 0.7)

Response 201 Created

{
  "data": {
    "memoryId": "mem_abc123",
    "content": "Prefers terse, bullet-pointed responses.",
    "type": "preference",
    "importance": 0.8
  },
  "meta": { "requestId": "req_abc123" }
}

---

GET /api/v1/stan/memories/stats

Get memory statistics for the current user: the total, the count per type, and when the first and latest memories were saved.

Scope: stan:execute

Response 200 OK

{
  "data": {
    "total": 12,
    "byType": {
      "preference": 5,
      "fact": 4,
      "context": 2,
      "instruction": 1
    },
    "oldest": "2025-01-04T08:15:00Z",
    "newest": "2025-02-15T09:30:00Z"
  },
  "meta": { "requestId": "req_abc123" }
}

oldest and newest are when the first and latest memories were saved (null when there are none).

---

DELETE /api/v1/stan/memories/:id

Delete a specific memory.

Scope: stan:execute

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Memory ID to delete

Response 204 No Content

---

DELETE /api/v1/stan/memories

Clear all memories for the current user. This action is irreversible.

Scope: stan:execute

Response 200 OK

{ "data": { "cleared": true }, "meta": { "requestId": "req_abc123" } }