專案總覽
專案簡介
Lore Vault 是給 coding agent（Claude Code 與其他 MCP 客戶端）使用的自架記憶服務。agent 把架構決策、踩過的坑與交接事項寫成筆記，之後在同一個專案內透過關鍵字加語意的混合檢索找回來。它取代了我先前以 Open Notebook 搭建的專案記憶系統，一個 docker compose 就能啟動 HTTP API、MCP 端點、Web UI 與備份。
核心理念
以專案為範圍：vault 由 git remote 自動對應，範圍在儲存層強制執行，跨專案查詢必須明示
先索引、後全文：查詢只回標題與摘要，需要時才取全文，不淹沒 context window
空間分離：開發（dev）、世界觀（lore）、私人（personal）三個 space 互不混用
可降級：服務不可達時，本機殼仍能以唯讀快照提供關鍵字檢索
我的職責
作為本專案唯一開發者，我負責：
系統架構設計
設計 space → vault → 筆記／文件段落的分層資料模型與 git remote 對應規則
規劃 SQLite FTS5 關鍵字與 embedding 向量的混合檢索管線
設計 HTTP 與 stdio 兩種 MCP 接入方式共用同一份工具定義
核心功能實作
檢索：FTS5 與 bge-m3 向量以 RRF 融合排序
ask：把檢索結果交給模型整理成逐點回答，並機械檢查引用的筆記 id
文件：上傳 PDF、Word、PowerPoint 後在背景切段並與筆記一起檢索
記憶管線：以 hook 收集 agent 工作片段，每日蒸餾成概念並在工具呼叫前注入
營運：doctor 對帳檢查、
VACUUM INTO驗證備份、啟動時自動 schema 遷移Web UI：搜尋、瀏覽與編輯筆記，管理文件與 vault，健康檢查與維護
核心功能
1. 專案範圍記憶
vault 依 git remote 正規化為 key，支援改名別名
所有讀寫都帶 vault，跨 vault 查詢必須明示
2. 混合檢索與 ask
SQLite FTS5 關鍵字加 Ollama
bge-m3向量，回傳受字數預算控制ask 以檢索結果產生附來源的回答，定位為參考而非唯一事實來源
3. MCP 接入
內建 Streamable HTTP 端點
/mcp，一行claude mcp add即可接入本機 stdio 殼可自動從工作目錄推算 vault，並在服務離線時降級為本地快照
4. 自架與發行
Docker Compose 一鍵啟動，可選 Ollama 與 cloudflared 隧道 profile
安裝 kit 支援
--update、--dry-run、--rollback，方便在其他機器接入
使用技術
後端
Python：主要開發語言（uv 管理）
FastAPI + Uvicorn：HTTP API
SQLite FTS5 + NumPy：關鍵字與向量檢索
MCP SDK：HTTP 與 stdio 兩種接入
AI / 檢索
Ollama（bge-m3）：1024 維 embedding
OpenAI API：摘要與 ask 回答
前端與部署
Vite + TypeScript：Web UI，Playwright 端對端測試
Docker Compose：自架部署
專案狀態
目前版本：v0.1.1
✅ 已取代舊專案記憶系統，舊資料 1455 則匯入並對帳一致
✅ 混合檢索、ask、文件檢索與 Web UI 上線
✅ 記憶管線每日蒸餾與概念注入運作中
✅ Docker 自架發佈與安裝 kit
🔄 持續改善檢索品質與多機接入流程
開發挑戰與成就
1. 中文查詢的全文檢索
挑戰：FTS 把中文問句組成整句片語，導致關鍵字幾乎無法命中。
解法：修正查詢組裝方式，並建立固定題組做回歸測試。
成果：59 題回歸的 top-10 命中率由 72.5% 提升到 85%。
2. 不中斷的系統切換
挑戰：要把日常在用的舊記憶系統換掉，同時不能遺失任何筆記。
解法：先匯入再逐筆對帳，舊系統保留觀察期作為退路。
成果：1455 則筆記完整遷移，所有 agent 與專案設定改指新服務。
3. 保護 context window
挑戰：記憶越多，agent 一次查詢吃掉的 context 越多。
解法：檢索只回標題與摘要並套用字數預算，全文按需取用。
未來規劃
擴充概念層的檢索支援
讓世界觀與創作資料也能放進 lore space 管理
通用化多機安裝流程
專案亮點
技術創新
✅ 儲存層強制的專案範圍，跨專案查詢必須明示
✅ FTS5 與向量以 RRF 融合的混合檢索
✅ 服務離線時的唯讀快照降級
開發品質
✅ 固定題組的檢索回歸測試
✅ 驗證式備份與啟動時 schema 遷移
技術棧：Python、FastAPI、SQLite FTS5、Ollama（bge-m3）、MCP、Vite + TypeScript、Docker 授權：MIT 目前階段：v0.1.1，日常使用中
