Memory API

Agent Memory 讓 AI 跨對話記住專案層級的規則、事實與時效性上下文。Memory 以 project 為唯一隔離維度，同一 project 下所有 API Key 共享相同記憶池。

需要 Basic+ 方案才能使用 Memory 功能。

記憶類型

類型	說明	注入方式
rule	行為規則，例如「回覆時不要使用 emoji」	全量注入（所有 active rules）
fact	事實性記憶，例如「專案使用 PostgreSQL 18」	語義檢索 Top-K
context	時效性上下文，可設定過期時間	語義檢索 Top-K + expires_at 過濾

---

建立記憶

POST /v1/memories

POST /v1/memories
Authorization: Bearer sk-your-api-key
Content-Type: application/json

{
  "content": "回覆時不要使用 emoji",
  "memory_type": "rule",
  "importance": 0.9,
  "expires_at": null
}

請求欄位：

欄位	類型	必填	說明
content	string	✓	記憶內容（1–10000 字元）
memory_type	string	✓	rule / fact / context
importance	number		0.0 – 1.0，越高越優先注入，預設 0.5
expires_at	string		RFC3339，主要供 context 類型使用；null 表示永久

回應（201 Created）：

{
  "success": true,
  "code": 1000,
  "message": "Success",
  "data": {
    "id": "019449a012347abc8def0123456789ab",
    "content": "回覆時不要使用 emoji",
    "memory_type": "rule",
    "importance": 0.9,
    "is_active": true,
    "created_at": "2026-05-08T12:00:00Z",
    "updated_at": "2026-05-08T12:00:00Z",
    "last_accessed_at": null,
    "expires_at": null
  }
}

---

列出記憶

GET /v1/memories

GET /v1/memories?memory_type=rule&page=1&page_size=20
Authorization: Bearer sk-your-api-key

查詢參數：

參數	類型	預設	說明
memory_type	string		篩選類型：rule / fact / context
page	number	1	頁碼
page_size	number	20	每頁筆數
sort_by	string	created_at	排序欄位：created_at / updated_at / importance
sort_dir	string	desc	排序方向：asc / desc

回應：

{
  "success": true,
  "code": 1000,
  "message": "Success",
  "data": {
    "memories": [
      {
        "id": "019449a012347abc8def0123456789ab",
        "content": "回覆時不要使用 emoji",
        "memory_type": "rule",
        "importance": 0.9,
        "is_active": true,
        "created_at": "2026-05-08T12:00:00Z",
        "updated_at": "2026-05-08T12:00:00Z",
        "last_accessed_at": null,
        "expires_at": null
      }
    ],
    "pagination": {
      "page": 1,
      "page_size": 20,
      "total": 42,
      "total_pages": 3
    }
  }
}

---

取得記憶詳情

GET /v1/memories/{memory_id}

GET /v1/memories/019449a012347abc8def0123456789ab
Authorization: Bearer sk-your-api-key

回傳單筆 AgentMemory 物件，格式同建立記憶的回應。

---

更新記憶

PUT /v1/memories/{memory_id}

PUT /v1/memories/019449a012347abc8def0123456789ab
Authorization: Bearer sk-your-api-key
Content-Type: application/json

{
  "content": "回覆時不要使用 emoji 或特殊符號",
  "importance": 0.95,
  "is_active": true,
  "expires_at": null
}

請求欄位（全部選填，至少傳一個）：

欄位	類型	說明
content	string	記憶內容；變更時自動重新計算 Embedding
memory_type	string	rule / fact / context
importance	number	0.0 – 1.0
is_active	boolean	是否啟用
expires_at	string / null	RFC3339；傳 null 表示清除過期設定

回傳更新後的 AgentMemory 物件。

---

刪除記憶

DELETE /v1/memories/{memory_id}

DELETE /v1/memories/019449a012347abc8def0123456789ab
Authorization: Bearer sk-your-api-key

回傳 204 No Content。

---

語義搜尋

POST /v1/memories/search

POST /v1/memories/search
Authorization: Bearer sk-your-api-key
Content-Type: application/json

{
  "query": "回覆風格規則",
  "memory_type": "rule",
  "top_k": 10,
  "min_similarity": 0.5,
  "include_expired": false
}

請求欄位：

欄位	類型	必填	說明
query	string	✓	搜尋文字（1–10000 字元）
memory_type	string		限定搜尋的記憶類型
top_k	number		回傳數量（1–50），預設 10
min_similarity	number		最低相似度門檻（0.0–1.0）
include_expired	boolean		是否包含已過期記憶，預設 false

回應：

{
  "success": true,
  "code": 1000,
  "message": "Success",
  "data": {
    "results": [
      {
        "memory": {
          "id": "019449a012347abc8def0123456789ab",
          "content": "回覆時不要使用 emoji",
          "memory_type": "rule",
          "importance": 0.9,
          "is_active": true,
          "created_at": "2026-05-08T12:00:00Z",
          "updated_at": "2026-05-08T12:00:00Z",
          "last_accessed_at": null,
          "expires_at": null
        },
        "similarity": 0.89,
        "final_score": 0.863
      }
    ],
    "query": "回覆風格規則",
    "total": 1
  }
}

回應欄位說明：

欄位	類型	說明
results[].memory	object	完整 AgentMemory 物件
results[].similarity	number	向量相似度（0.0–1.0）
results[].final_score	number	綜合分數 = similarity × 0.7 + importance × 0.3；結果依此排序
query	string	原始搜尋文字
total	number	符合條件的結果總數

---

自動萃取記憶

POST /v1/memories/extract

讓 LLM 從文字中自動識別並儲存值得記住的資訊。會消耗少量 Credits。

POST /v1/memories/extract
Authorization: Bearer sk-your-api-key
Content-Type: application/json

{
  "text": "我是前端工程師，主要使用 React 和 TypeScript。",
  "deduplicate": true
}

請求欄位：

欄位	類型	必填	說明
text	string	✓	要萃取的文字（1–50000 字元）
deduplicate	boolean		是否去重，預設 true

回應：

{
  "success": true,
  "code": 1000,
  "message": "Success",
  "data": {
    "extracted": [
      {
        "id": "019449a0aaaa7abc8def0123456789ab",
        "content": "使用者是前端工程師，主要使用 React 和 TypeScript",
        "memory_type": "fact",
        "importance": 0.7,
        "expires_at": null,
        "action": "created"
      }
    ],
    "deduplicated": 0,
    "updated": 0
  }
}

回應欄位說明：

欄位	類型	說明
extracted[].action	string	created / updated / skipped
deduplicated	number	跳過數量（cosine similarity > 0.98，視為完全重複）
updated	number	更新數量（cosine similarity > 0.90，更新既有記憶）

---

批次刪除

DELETE /v1/memories

DELETE /v1/memories
Authorization: Bearer sk-your-api-key
Content-Type: application/json

{
  "memory_type": "context"
}

memory_type 為選填。不傳則刪除整個 project 下的所有記憶；傳入則只刪除指定類型。

回應：

{
  "success": true,
  "code": 1000,
  "message": "Success",
  "data": {
    "deleted_count": 15
  }
}

---

錯誤碼

錯誤碼	HTTP	說明
2100	404	記憶不存在
2101	400	記憶數量超過方案上限
2103	500	LLM 萃取失敗
2104	409	重複的記憶
2106	403	記憶功能未啟用（需 Basic+ 方案）

---

所需權限

操作	所需權限
讀取、搜尋	memory.read
新增、修改、刪除、萃取	memory.write