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 記住你的技術棧和工作方式，之後的問答都不用再重複說明背景。

// 一次設定，長期生效
await client.memories.create({
  content: '使用 React 19 + TypeScript，後端是 Go，偏好函數式寫法，回覆使用繁體中文',
  memory_type: 'rule',
  importance: 1.0,
});

// 之後問問題，AI 自動記得你的技術棧
const reply = await client.chat.completions.create({
  model: 'openai/gpt-4o',
  messages: [{ role: 'user', content: '怎麼做 API error handling 比較好？' }],
  vecstruct: { use_memory: true },
});
// AI 會用 TypeScript/Go 舉例，而且用繁體中文回覆

常見情境： 程式碼助手、技術問答工具、個人 AI 助手

範例二：自動從對話萃取記憶

不用手動建立記憶，讓 AI 從對話中自動找出值得記住的資訊。

// 對話結束後自動萃取
await client.memories.extract({
  messages: [
    { role: 'user', content: '我正在做一個線上學習平台，前端 Next.js，後端 Python FastAPI' },
    { role: 'assistant', content: '了解，之後範例會對應這個 stack' },
    { role: 'user', content: '我偏好 async/await，不習慣用 callback' },
  ],
});
// 自動萃取並儲存：「Next.js 前端」「Python FastAPI 後端」「偏好 async/await」

常見情境： 長期互動的 AI 應用、學習工具、個人化助手

範例三：記住學習進度的教育輔助工具

記住學生已學會哪些概念、哪些還不熟，之後輔導時自動調整深度，不重複解釋已懂的內容。

// 練習完成後記錄學習狀況
await client.memories.create({
  content: '已掌握 async/await 基礎，但對 Promise.all 和 race 的差別還不清楚',
  memory_type: 'fact',
  importance: 0.8,
});

// 下次輔導自動調整內容
const reply = await client.chat.completions.create({
  model: 'openai/gpt-4o',
  messages: [{ role: 'user', content: '幫我解釋 Promise 的併發控制' }],
  vecstruct: { use_memory: true },
});
// AI 知道你已懂基礎，會直接聚焦在 Promise.all / race 的差異

常見情境： 語言學習 App、程式學習平台、個人化課程工具

範例四：長期 SaaS 個人化

在你的 SaaS 裡讓 AI 記住每個用戶的使用習慣，提供個人化體驗。

// user_id 區隔不同用戶的記憶
await client.memories.create({
  content: '喜歡看圖表，不喜歡長段落文字說明',
  memory_type: 'rule',
  importance: 0.9,
  metadata: { user_id: 'user-456' },
});

常見情境： SaaS 產品個人化、AI 寫作工具、個人理財 App

---

記憶的 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 方案以上