Agent Memory

Agent Memory 讓 AI 記住跨對話的資訊——使用者偏好、重要事實、行為規則。每次對話都能自動注入相關的記憶，讓 AI 的回覆更個人化。

簡單說：你告訴 AI 你喜歡什麼、你的習慣是什麼，下次對話 AI 還記得。

記憶的類型

每條記憶都有一個類型：

類型	說明	範例
rule	規則或偏好，AI 應該遵守的行為準則	「總是用繁體中文回覆」
fact	關於使用者的事實	「使用者是後端工程師，使用 Go」
context	對話上下文，短期情境資訊	「目前在討論 API 設計」

快速上手

新增記憶

Node.js

import { Vecstruct } from '@vecstruct/sdk';

const client = new Vecstruct({ apiKey: process.env.VECSTRUCT_API_KEY });

// 新增一條規則記憶
const mem = await client.memories.create({
  content: '使用者偏好繁體中文，技術術語保留英文',
  memory_type: 'rule',
  importance: 0.9,    // 0.0 - 1.0，越高越重要，AI 越優先注入
});

console.log('記憶 ID:', mem.id);

Python

from vecstruct import AsyncVecstruct

async with AsyncVecstruct() as client:
    mem = await client.memories.create(
        content="使用者偏好繁體中文，技術術語保留英文",
        memory_type="rule",
        importance=0.9,
    )
    print("記憶 ID:", mem["id"])

Go

// Go SDK Memory 操作
// 詳見 Go SDK 文件

在對話中啟用 Memory

Node.js

const reply = await client.chat.completions.create({
  model: 'openai/gpt-4o',
  messages: [{ role: 'user', content: '幫我 review 這段程式碼' }],
  vecstruct: {
    use_memory: true,   // 自動注入相關記憶
  },
});

// AI 會記得你之前設定的偏好（例如用繁體中文回覆）
console.log(reply.choices[0].message.content);
console.log('是否有注入記憶:', reply.vecstruct?.memory_used);

Python

reply = await client.chat.completions.create(
    model="openai/gpt-4o",
    messages=[{"role": "user", "content": "幫我 review 這段程式碼"}],
    vecstruct={
        "use_memory": True,
    },
)
print(reply["choices"][0]["message"]["content"])

Go

useMemory := true
resp, err := client.CreateChatCompletion(ctx, vecstruct.ChatCompletionRequest{
    Model: "openai/gpt-4o",
    Messages: []vecstruct.ChatMessage{
        {Role: "user", Content: "幫我 review 這段程式碼"},
    },
    Vecstruct: &vecstruct.VecstructParams{
        UseMemory: &useMemory,
    },
})

從對話自動萃取記憶

讓 AI 自動從對話中找出值得記住的資訊：

Node.js

await client.memories.extract({
  messages: [
    { role: 'user', content: '我用 React 19 + TypeScript，後端是 Go' },
    { role: 'assistant', content: '了解，之後範例會用這個 stack' },
    { role: 'user', content: '我偏好函數式寫法，避免使用 class' },
  ],
});
// AI 會自動萃取並儲存「React 19 + TypeScript」「Go 後端」「偏好函數式」等記憶

Python

extracted = await client.memories.extract(
    text="我習慣用 Python 非同步程式設計，偏好 FastAPI 框架",
    deduplicate=True,   # 避免存入重複的記憶
)
print(f"萃取了 {len(extracted)} 條記憶")

Go

// Go SDK Memory 萃取
// 詳見 Go SDK 文件

搜尋記憶

Node.js

// 語義搜尋，找與查詢最相關的記憶
const hits = await client.memories.search({
  query: '使用者的程式語言偏好',
  top_k: 5,
});

for (const hit of hits) {
  console.log(`內容: ${hit.content}`);
  console.log(`相似度: ${hit.score.toFixed(3)}`);
}

Python

results = await client.memories.search(
    query="使用者的程式語言偏好",
    top_k=5,
    min_similarity=0.5,
)
for r in results:
    print(f"[{r['memory_type']}] {r['content']} (相似度: {r['score']:.3f})")

Go

// Go SDK Memory 搜尋
// 詳見 Go SDK 文件

---

應用場景範例

範例一：個人化 AI 助手

讓 AI 記住每個使用者的偏好和習慣，打造真正個人化的體驗。

解決的問題： 每次對話都要重新告訴 AI 你的偏好和背景，浪費時間。

用 Vecstruct 怎麼做：

1. 第一次使用時，讓使用者填寫偏好設定（語言、技術棧、工作角色等）
2. 把這些存成 rule 和 fact 類型的記憶
3. 之後每次對話都開啟 use_memory: true，AI 自動記得這些偏好

// 使用者設定偏好
await client.memories.create({
  content: '使用者是 iOS 開發者，主要用 Swift，需要繁體中文回覆',
  memory_type: 'rule',
  importance: 1.0,
});

// 之後的每次對話都能記得
const reply = await client.chat.completions.create({
  model: 'openai/gpt-4o',
  messages: [{ role: 'user', content: '怎麼用 SwiftUI 做動畫？' }],
  vecstruct: { use_memory: true },
});
// AI 會自動用繁體中文回覆，且聚焦在 iOS 相關的用法

範例二：客戶服務歷史記憶

讓客服 AI 記住每個客戶的歷史、已解決的問題、特殊需求。

解決的問題： 客戶每次聯繫都要重新解釋問題背景，服務體驗差。

用 Vecstruct 怎麼做：

1. 每次客戶互動結束後，呼叫 memories.extract 自動萃取關鍵資訊
2. 下次客戶聯繫時，注入相關記憶
3. 客服 AI 能直接說「根據您上次反映的問題，我們...」

範例三：教育輔助平台的學習記錄

記住學生的學習進度、弱點、已掌握的概念，提供針對性的輔導。

解決的問題： 每個學生的學習狀況不同，但傳統 AI 對每個人都一視同仁。

用 Vecstruct 怎麼做：

1. 每次學生完成練習後，記錄哪些概念已理解、哪些還不熟
2. 下次輔導時，AI 自動調整解說的深度，不重複已學會的內容

---

記憶的 CRUD 操作

列出記憶

Node.js

const list = await client.memories.list({
  memory_type: 'rule',    // 只列出規則類型
  page: 1,
  page_size: 20,
});

console.log(`共 ${list.pagination.total} 條記憶`);
for (const mem of list.memories) {
  console.log(`[${mem.memory_type}] ${mem.content}`);
}

Python

memories = await client.memories.list(
    memory_type="rule",
    page=1,
    page_size=20,
)
for mem in memories["memories"]:
    print(f"[{mem['memory_type']}] {mem['content']}")

更新記憶

await client.memories.update(mem.id, {
  importance: 0.5,    // 降低重要性
});

刪除記憶

// 刪除單條
await client.memories.delete(mem.id);

// 批次刪除（例如清除某使用者的所有 context 類型記憶）
await client.memories.batchDelete({ memory_type: 'context' });

---

注意事項

• Memory 以專案為隔離單位，同一專案下的所有 API Key 共享記憶池
• memory.read 權限可讀取記憶；memory.write 權限可新增/修改/刪除
• LLM 自動萃取（extract）會消耗 Credits（費率詳見 Pricing）
• Memory 功能需要 Basic 方案以上