LucieEveille/kiwi-mem

🥝 kiwi‑mem – AI 作為大腦

是什麼

• 一個位於聊天客戶端與大型語言模型（LLM）API（OpenAI 兼容或 Anthropic 原生）之間的自托管網關。它在每次請求中注入 類人 的長期記憶，並從模型的回應中提取新的記憶片段。

核心理念

• 記憶熱度 – 每個儲存的事實都有一個「溫度」。它會隨時間冷卻，當對話重新提及時會升溫，若很少被提及則冷卻得更快。熱度高的記憶會完整注入，溫熱的以摘要形式注入，冷的則被忽略。
• 夢境（睡眠）週期 – 每晚執行的流程，清理過時的碎片，將相關片段合併為 記憶場景，並運行小型推理步驟以推斷未明說的事實。結果以高階記憶形式存回。
• 日曆壓縮 – 聊天記錄會自動匯總為分層摘要（日 → 週 → 月 → 季度 → 年），使舊時期僅佔用少量 token。
• 衝突解決與鎖定 – 當新事實與舊事實矛盾時，舊條目將被廢棄。使用者可鎖定重要記憶，使其永不衰減。
• 節省 token 的提示佈局 – 靜態資料（角色設定、鎖定記憶、日曆）置於快取前綴中，動態資料（搜尋結果、睡眠提示）隨後，可減少高達 ~90% 的輸入 token 成本。

如何運作

1. 你的聊天客戶端向 https://your‑domain/v1/chat/completions 發送請求（kiwi‑mem 網關）。
2. 網關使用混合 RRF 搜尋（向量 + 關鍵字）查找相關記憶，並根據其熱度水平將其前置到提示中。
3. 請求被轉發至設定的 LLM 提供商。
4. LLM 的回應返回給客戶端 並 被解析以提取新的記憶片段，這些片段以初始熱度儲存。
5. 定期（或按需）執行 Dream 任務以整合與推論。

主要功能

功能	作用
基於熱度的衰減與強化	記憶自動衰減；重複提及可重新加熱。
夢境睡眠整合	三階段清理、合併與前瞻推理。
分層日曆	日 → 週 → 月 → 季度 → 年的摘要，注入時細節遞減。
衝突處理	新的矛盾事實會停用舊條目；鎖定的記憶永久保留。
工具抽屜	20 多個內建工具（搜尋、提醒、網頁搜尋等）僅在系統預測需要時載入，節省 token。
多提供方支援	支援任何 OpenAI 兼容端點 和 Anthropic 原生 API，無需額外轉換。
專案隔離	全域記憶共享，但每個「專案」可擁有私有指令、檔案和對話歷史，永不洩漏給其他專案。
Web 管理面板	設定提供方、檢視/編輯記憶、執行 Dream、管理專案、匯出/匯入備份。
Docker 優先部署	docker compose up -d 一鍵啟動完整堆疊（FastAPI 網關 + PostgreSQL + pgvector）。

技術堆疊

• Python + FastAPI – HTTP 網關與記憶邏輯。
• PostgreSQL + pgvector – 儲存記憶、嵌入向量與熱度值。
• Docker / Docker‑Compose – 一鍵部署，可在 VPS、雲端虛擬機或 Zeabur 等平台間輕鬆遷移。
• AGPL‑3.0‑or‑later – 確保任何托管修改版本均保持開源。

適合誰

• 需要記住你的習慣、偏好、健康資料等的個人 AI 助手。
• 長期聊天夥伴（情感支援、角色扮演、講故事）。
• 需要在多次會話中保留世界觀細節的創意夥伴。
• 跟蹤你進度與弱點的學習導師。

快速入門

# 在新伺服器上
curl -fsSL https://get.docker.com | sh
git clone https://github.com/LucieEveille/kiwi-mem.git
cd kiwi-mem
cp .env.example .env   # 僅當你想預填 API_KEY 時才編輯
docker compose up -d

• 用 curl http://localhost:8080 驗證 → "status":"running"。
• 打開 https://your‑domain/admin（預設無密碼）添加 LLM 提供方，測試連線，並透過支援 OpenAI 風格 API 的任意客戶端開始聊天。

更新方法

• 執行 bash scripts/update.sh – 自動備份資料庫，拉取最新程式碼，重建容器，若新版本無法啟動則自動回滾。
• 可選安裝 cron（--install‑cron）實現每日自動更新。

限制

• 專為 個人記憶 設計，不適用於企業文件搜尋或知識圖譜場景。
• 網關本身無認證；若公開暴露，必須保護端點（如 Cloudflare Access、基本認證、IP 白名單）。

許可證

• AGPL‑3.0‑or‑later – 可使用、修改、分發，但若透過網路提供服務，必須向使用者公開原始碼（含你的修改）。

---

kiwi‑mem 致力於打造一個真正「記住你」的 AI，其遺忘與整合機制模仿人類記憶。