Memories

Endpoints for managing conversation memories and vector-based context retrieval.

GET /api/chats/{id}/memories

List all memories associated with a chat, including message counts.

Authentication: Required (session)

Pre-blocks: chat.lookup

Response:

{
  "_links": {
    "self": { "href": "/api/chats/{id}/memories" }
  },
  "_embedded": {
    "inf:memory": [
      {
        "id": "mem-123",
        "chatId": "chat-456",
        "summary": "Discussion about Q4 revenue targets and growth strategies",
        "reason": "topic_change",
        "messageCount": 12,
        "createdAt": "2024-01-15T10:45:00Z",
        "updatedAt": "2024-01-15T10:45:00Z"
      },
      {
        "id": "mem-124",
        "chatId": "chat-456",
        "summary": "Analysis of customer retention metrics",
        "reason": "completed_discussion",
        "messageCount": 8,
        "createdAt": "2024-01-15T11:20:00Z",
        "updatedAt": "2024-01-15T11:20:00Z"
      }
    ]
  },
  "start": 0,
  "count": 2,
  "total": 2
}

Memory Properties:

Field	Type	Description
id	string	Unique memory ID
chatId	string	Parent chat ID
summary	string	Text summary of the conversation segment
reason	string	Why the memory was created (see reasons below)
messageCount	integer	Number of messages in this memory
createdAt	date	When the memory was created
updatedAt	date	Last update timestamp

Memory Creation Reasons:

• user_created - Manually created by user
• completed_discussion - Natural conversation endpoint
• topic_change - Shift to new topic detected
• length_threshold - Message count reached threshold
• time_threshold - Time gap in conversation

---

POST /api/chats/{id}/memories

Create a new memory from chat messages.

Authentication: Required (session)

Pre-blocks: chat.lookup

Request Body:

Field	Type	Required	Description
messageIds	array	Yes	Array of message IDs to include
summary	string	No	Custom summary (auto-generated if omitted)
reason	string	No	Creation reason (default: user_created)

Example Request:

{
  "messageIds": ["msg-123", "msg-124", "msg-125"],
  "summary": "Initial project requirements discussion",
  "reason": "user_created"
}

Response:

{
  "id": "mem-789",
  "chatId": "chat-456",
  "summary": "Initial project requirements discussion",
  "reason": "user_created",
  "messageCount": 3,
  "embedding": [0.023, -0.145, ...],
  "createdAt": "2024-01-15T12:00:00Z"
}

Memory Generation:

If no summary is provided, the system generates one using AI by:

1. Extracting content from all referenced messages
2. Sending to configured summarization model
3. Creating vector embedding from the summary
4. Storing for semantic search

---

GET /api/memories/{id}

Retrieve a single memory with associated messages and files.

Authentication: Required (session)

Pre-blocks: memory.lookup

Response:

{
  "id": "mem-123",
  "chatId": "chat-456",
  "summary": "Discussion about Q4 revenue targets and growth strategies",
  "reason": "topic_change",
  "embedding": [0.023, -0.145, ...],
  "messages": [
    {
      "id": "msg-101",
      "role": "user",
      "content": "What were our Q4 targets?",
      "createdAt": "2024-01-15T10:30:00Z"
    },
    {
      "id": "msg-102",
      "role": "assistant",
      "content": "The Q4 targets were $2.5M...",
      "createdAt": "2024-01-15T10:30:15Z"
    }
  ],
  "files": [
    {
      "id": "file-789",
      "filename": "Q4_report.pdf",
      "size": 204800
    }
  ],
  "createdAt": "2024-01-15T10:45:00Z",
  "updatedAt": "2024-01-15T10:45:00Z"
}

---

PUT /api/memories/{id}

Regenerate a memory's summary and embedding.

Authentication: Required (session)

Pre-blocks: memory.lookup

Request Body:

Field	Type	Required	Description
action	string	Yes	Must be regenerate

Example Request:

{
  "action": "regenerate"
}

Response:

Returns the memory object with updated summary and embedding.

Use Cases:

• Fix poor auto-generated summaries
• Update after editing message content
• Re-embed with improved models

---

DELETE /api/memories/{id}

Delete a memory and its associated vector embedding.

Authentication: Required (session)

Pre-blocks: memory.lookup

Response:

204 No Content

Side Effects:

• Removes memory record
• Deletes vector embedding from search index
• Breaks association with messages (messages remain)

---

POST /api/chats/{id}/memories/search

Perform semantic search on memories using vector similarity.

Authentication: Required (session)

Pre-blocks: chat.lookup

Request Body:

Field	Type	Required	Description
query	string	Yes	Search query (1-500 characters)
limit	integer	No	Max results (1-20, default: 5)

Example Request:

{
  "query": "revenue growth strategies",
  "limit": 5
}

Response:

{
  "results": [
    {
      "memory": {
        "id": "mem-123",
        "summary": "Discussion about Q4 revenue targets and growth strategies",
        "messageCount": 12
      },
      "score": 0.87,
      "rank": 1
    },
    {
      "memory": {
        "id": "mem-456",
        "summary": "Annual revenue planning session",
        "messageCount": 8
      },
      "score": 0.72,
      "rank": 2
    }
  ],
  "query": "revenue growth strategies",
  "limit": 5
}

Scoring:

• score - Cosine similarity (0.0 to 1.0)
• Higher scores indicate better matches
• Typically threshold at 0.6 for relevance

Implementation:

1. Query text is embedded using the same model as memory creation
2. Vector similarity search finds closest matches
3. Results ordered by similarity score descending
4. Limited to specified result count

Context Retrieval

Memory search is used to inject relevant context into AI conversations, improving response quality by retrieving past discussions on similar topics.

Performance

Vector search typically completes in under 100ms for up to 10,000 memories per chat. Larger memory sets may benefit from pagination or filtering.