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
offset	integer	No	Pagination offset

Response 200 OK

{
  "count": 12,
  "limit": 20,
  "offset": 0,
  "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
    }
  ]
}

---

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

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

---

GET /api/v1/stan/memories/stats

Get memory statistics for the current user (counts by type, totals, decay summary).

Scope: stan:execute

Response 200 OK

{
  "total": 12,
  "byType": {
    "preference": 5,
    "fact": 4,
    "context": 2,
    "instruction": 1
  },
  "averageImportance": 0.72
}

---

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

{
  "cleared": true
}