jzjzzzzzzz/agent-me

Distill your knowledge, memories, and decisions into an open-source, inspectable AI Agent Twin.

Agent‑Me – 你的開源「AI雙胞胎」

是什麼 – Agent‑Me 是一個可執行的 FastAPI + React 應用，可將版本控制的 Markdown 個人知識庫轉換為小型、可檢視的 AI 代理。該代理不僅複述事實，還遵循一個決定論的多階段流程（檢索 → 規劃 → 研究 → 批判 → 寫作 → 可選驗證），並返回完整的執行軌跡，使每個回答都有證據支持且可審計。

為何重要 – 多數個人聊天機器人僅依賴單一提示詞加向量儲存。Agent‑Me 將個人 AI 視為一個具有顯式記憶、來源和基於證據回答的系統。所有中間步驟均公開，可查看雙胞胎為何如此回答，並在證據不足時阻止合成。

核心概念

組件	角色	實現（如 README 所述）
個人知識	雙胞胎的靜態事實、偏好、經驗等	可審查的版本控制 Markdown 檔案（例如 `knowledge/example-profile.md`）。
RAG	在回答前查找相關摘錄。	作用於 Markdown 語料庫的有界、決定性本地檢索器。
規劃者	決定回答問題的整體方法。	產生類型化的 `Plan` 資料類別。
研究者	拉取計畫所需的精確來源摘錄。	回傳包含摘錄和元資料的 `EvidenceBundle`。
批評者	檢查證據是否足以進行合成。	發出 `Critique`；若證據不足，可返回「證據不足」固定回應以阻斷流程。
寫作者	生成最終答案，引用證據。	發出包含引用和安全摘要的 `WrittenAnswer`。
驗證者 (可選)	對引用路徑和其他不變量進行額外檢查。	產生 `Verification` 結果；若檢查失敗，可拒絕答案。
公開軌跡	使整個執行過程可觀測。	包含每個階段結果、安全摘要和指標的 JSON 負載。
評估	保證回歸測試中的決定性行為。	版本化固定用例（`course/fixtures/...`）和決定性評估器在 CI 中執行。

工作原理（高階流程）

使用者發送請求 到 /api/v1/collaborate（或聊天端點）。請求包含問題和期望的工作流（default = 規劃者‑研究者‑批評者‑寫作者，verified = 加入驗證者）。
檢索從本地語料庫中提取相關 Markdown 摘錄。
規劃者 建立一個結構化計畫，描述需要回答的內容。
研究者 收集計畫所需的精確摘錄。
批評者 驗證收集到的證據是否充分；若不充分，返回固定「證據不足」回覆。
寫作者 組合出引用意識的答案。
驗證者（啟用時）檢查引用路徑和其他不變量；失敗則被阻斷。
回應包含答案、來源清單、grounded 標誌和每個階段的完整 trace。

快速入門

方法	步驟
Docker Compose（推薦）	1️⃣ `git clone https://github.com/jzjzzzzzzz/agent-me.git` 2️⃣ `cd agent-me && cp .env.example .env` 3️⃣ `docker compose up --build` 在 http://localhost:5173 訪問 UI，在 http://localhost:8000/docs 訪問 API 文件。
本地工具鏈	需要 Python 3.11+、`uv`、Node 22+、npm。執行 `make setup`，然後啟動後端（`uvicorn …`）和前端（`npm run dev`）。
可選 LLM 提供商	在 `.env` 中設定 `LLM_BASE_URL`、`LLM_API_KEY` 和 `LLM_MODEL`，指向 OpenAI 兼容端點（例如 OrcaRouter）。僅 `/api/v1/chat` 端點使用外部模型；`/collaborate` 保持完全本地運行。

典型用例

個人知識助手 – 向雙胞胎提問關於你自己的專案、偏好或過去決策的問題，獲得引用確切 Markdown 條目的答案。
研究可重現性 – 公開軌跡允許你審計結論是如何得出的，對合規或學術環境很有用。
教育示範 – 倉儲包含雙語課程，引導開發者逐步建構該流程。
持續學習 AI 雙胞胎原型 – 架構故意模組化，可替換 Markdown 儲存為更豐富的圖結構，添加基於同意的攝入，或接入工具呼叫模組。

限制（如倉儲所述）

當前記憶是靜態的 Markdown 檔案集；無自動攝入或遺忘功能。
結構化身分模型、時間推理和置信度評分是 未來工作。
驗證者僅檢查引用路徑不變量；不保證事實真實性。
使用外部 LLM 提供商時，僅聊天端點傳送資料到外部；核心協作流程保持本地。
該系統是 實驗性架構，非生產就緒的個人助手。

接下來查看

架構細節 – docs/ARCHITECTURE.md
API 模式 – docs/API.md
信任模型 – docs/TRUST.md
路線圖與貢獻 – ROADMAP.md 和 CONTRIBUTING.md
評估固定用例 – course/fixtures/collaboration_cases.json

總結 – Agent‑Me 是一個具體的開源平台，用於建構一個將個人知識以可檢視形式儲存，並透過透明、多代理流程回答問題的「AI 雙胞胎」。它有意受限（本地檢索、決定性執行），但設計為可擴展，以實現持續學習、保護隱私的個人數位化身。