name: agent-local-memory-keeper slug: agent-local-memory-keeper displayName: AI Agent記憶系統 description: 給 AI Agent 的跨會話長期記憶系統：用自然語言記經驗，需要時自動語義召回，並自動去重、糾錯、分層歸檔。專治 AI 反覆忘事、重複問同樣問題、把過時結論當真。預設純本地零雲端，自然語言驅動，內建防反覆確認死迴圈閘門；本地 fastembed 語義召回為預設，跑不動自動回退詞法級。內建敏感資訊攔截與可選加密。 summary: 給 AI 的長期記憶：自然語言記經驗、跨會話自動召回、自動去重糾錯分層；本地優先、防自反饋死迴圈。 tags: - 記憶管理 - AI Agent - 長期記憶 - 本地優先 - 語義召回 - 知識庫 - 自動化 license: MIT agent_created: true version: 4.8.1

AI Agent 記憶系統

🚀 5 分鐘上手（新使用者只看這三步）

1. 裝上 skill — 這是本地優先執行的 skill（可經 SkillHub 安裝，執行時不依賴任何雲端），裝完即獲得預設能力、零配置（詳見 QA.md「裝完還要配置嗎」）。
2. 對 AI 說"幫我一鍵配好" — AI 替你跑完鉤子 / 守護 / 中文語義等所有裝後步驟，不用手敲任何命令；想要"自動記憶"就補一句"順便開自動記憶"。
3. 想自己跑也行，一條命令等價：python scripts/keeper_setup.py all（零配置收口全部裝後步驟）。
4. 開始用 — 直接對 AI 說"記一下這個坑""幫我整理今天記的"；或翻 references/TUTORIAL.md 的真實樣例。

💡 只想手動記/找、不要後臺程序？完全可以——跳過"自動記憶"，直接 deposit / recall 照樣工作（見下方「輕量模式」）。守護程序不是必需的。

🗺️ 文件導航（想做 X → 看哪裡，不用全讀）

你想…	看這裡	分級
所有能力一句話觸發（記/找/整理/分類/鉤子/配置）	本檔案「四、§4.1 對話入口」	Tier1
一步步上手 + 真實返回樣例	references/TUTORIAL.md	Tier1
新手最常遇到的 5 個問題（先看這個）	references/QA.md	Tier1
2 分鐘極簡上手（不想讀長文件）	QUICKSTART.md	Tier1
讓 AI 幫你裝 / 配（不手敲命令）	references/TUTORIAL.md §0.5 / references/COOKBOOK.md	Tier1
所有命令 + 引數	references/COMMANDS.md	Tier2
裝 fastembed / 加密 / Ollama（含排錯）	references/INSTALL.md	Tier2
所有限制 / 紅線一覽	references/LIMITS.md	Tier2
鉤子 / 守護程序 / 定時 / IMA 同步 實操	references/COOKBOOK.md	Tier2
特性深讀（召回 / 矛盾 / 加密 / 語義後端 / ANN / 跨語言）	references/FEATURES.md	Tier2
儲存架構 / 資料模型（進階）	references/FORMAT_ANALYSIS.md	Tier2
記憶型別分類法	references/TYPE_TAXONOMY.md	Tier2
能力開啟「三桶分類」嚮導	references/ENABLEMENT.md	Tier2
場景/記憶型別分類嚮導話術	references/taxonomy_wizard.md	Tier2
mem_bridge 全部橋接命令（含內部命令）	references/MEM_BRIDGE.md	Tier2
版本歷史	根 CHANGELOG.md（唯一權威源）	Tier3

📚 文件分級（按需取用，不必全讀）：Tier1 必看（約 5 分鐘） = QUICKSTART.md（極簡上手）+ 本檔案對話入口 + TUTORIAL.md + QA.md；Tier2 進階 = 命令/安裝/限制/菜譜/特性；Tier3 開發者內部 = references/_design/（設計稿與測試協議，普通使用者無需看）。

一、這是什麼

這是一個給 AI 用的長期經驗筆記本：你（或 AI）把"有用的結構化經驗"丟進去，它會自動去重、發現新舊結論衝突、按重要程度分層、過期歸檔，跨會話越用越聰明。預設純本地、零雲端；可選的線上元件（雲端 embeddings / 雲端 LLM / IMA 知識庫映象）需你主動開啟，不開則全程不聯網。

它適合沉澱經驗——踩過的坑、糾正過的結論、反覆驗證的最佳實踐；不是錄影帶，不會搬運整段對話上下文。內建語義召回、冷熱分層、敏感資訊攔截和加密選項，你可以完全用自然語言使喚它（"記一下這個坑""幫我整理今天記的"），AI 會自動呼叫背後的命令。

資料存在哪：預設 Windows 有 D 盤放 D:/AI記憶，否則使用者目錄；mac/Linux 放 ~/.ai-memory。store/index.db（SQLite，WAL）是當前權威源（含持久化向量與可索引欄位）；memories/*.json 是與之雙向同步的人類可讀副本，可整體備份/遷移/人眼檢查；index.json 為兜底匯出（SQLite 損壞時由 rebuild 從檔案重建）；寫入即同步、doctor 兜底校驗。整套記憶純本地、跨裝置可攜帶——把整個資料夾（含 store/ 與 memories/）拷到任何電腦，配好 AI_MEMORY_STORE 指向它，記憶就原樣帶過去了。 可選加密：設 AI_MEM_ENCRYPTION_KEY 後文件與索引 summary 均加密，忘 key 則資料永久丟失（務必手抄恢復碼）。

二、怎麼運轉 / 如何工作

三層架構（並存、按需取用）： - ① 語義召回層（核心，開箱即用）：store/index.db（SQLite 權威源）+ memories/*.json（雙向同步的可讀副本）+ 向量語義召回 + 結構化標籤 + 冷熱分層 + 加密 + 矛盾檢測 + 防自反饋閘門（+ 可選 IMA 橋接）。index.db 是權威源，memories/*.json 與 index.json 為同步副本/兜底（寫入即同步，doctor 兜底校驗），詳見 references/FORMAT_ANALYSIS.md。 - ② 行為規則層（手動觸發）：高頻/已確認經驗可固化成 AI 每輪行為規則（export-rules 寫入 AGENTS.md 等目標檔案），讓記憶直接改變行為，而非僅被 recall 命中。另支援 --rules-target text：寫到 --out 任意路徑，避開 Copilot/Claude 平臺自動載入（合規/隔離用）。 - ③ 輕量檔案層（opt-in）**：--flat 模式跳過 SQLite 與 LLM，全部落純 Markdown 檔案、grep 召回，給只想"記個坑"的零依賴使用者。

核心迴圈（記 → 找 → 理 → 沉），且全程不刪你的記憶： 1. 記 deposit — 寫經驗 + 自動去重 + 敏感攔截；糾正舊結論用 --corrects <舊id>，舊記憶自動標 superseded。 2. 找 recall — 語義/詞法/標籤多維召回，支援 --filter 數值 DSL 與 --max-age-days 新鮮度過濾。 3. 理 reflect --auto — 去重 / 糾錯 / 晉升 / 歸檔，絕不刪除 active 記憶。 4. 沉 decay --apply — 長期不命中的記憶確定性降權沉底（仍 recall --deep 可找回）。

🪶 輕量模式（不裝守護程序也能用）：守護程序只是"讓鉤子自動記憶時 recall 毫秒級"的可選增強，並非必需。 - 只想手動 deposit / recall：完全不用裝守護程序 / 定時任務，開箱即用（預設詞法召回，或設 AI_MEM_EMBED_BACKEND=fastembed / 線上 embeddings 開語義）。 - 想要自動記憶（AI 每輪自動記 + 召回）：跑一條命令 python scripts/keeper_setup.py hooks --scheduler 即可——它自動註冊鉤子 + 啟動守護 + 註冊每週排程（等價於 install_hooks.py + setup_scheduler.py）。 - 不要後臺程序又想要語義召回？選線上 embeddings 後端（本地零模型、零算力），鉤子 recall 走雲端向量、無需本地守護。

📚 儲存架構、狀態機、真源邊界等深讀見 references/FORMAT_ANALYSIS.md；特性原理見 references/FEATURES.md。

三、有哪些功能（能力一覽）

系統圍繞「分類 → 分層 → 檢索 → 進化 → 安全」五條線增強，全部純加性、不破壞舊庫：

逐項能力詳解（觸發條件 / 效能 / 邊界）見 references/FEATURES.md 與 references/LIMITS.md；IMA / 鉤子 / 守護程序實操見 references/COOKBOOK.md。

四、這些功能如何開啟

4.1 對話入口（所有能力，一句話觸發）

你永遠不用讀配置、不用記命令、不用手敲任何環境變數。 keeper 的每一項能力——記 / 找 / 整理 / 分類 / 鉤子 / 配置 / 體檢 / 自動化 —— 都可以通過自然語言對話完成。AI 在後臺替你跑對應命令，每步回顯結果。

🧭 怎麼用這個對話（三步）： 1. 直接說人話描述你想幹什麼——「記一下…」「找一下之前那個…」「幫我整理今天記的」「配 IMA 同步」——AI 自動路由到對應能力，你不用懂命令、不用看輸出。 2. 不知道能讓你做什麼？ 直接問「你能幫我管理記憶系統做哪些事」，AI 會列出全部能力（記 / 找 / 整理 / 分類 / 鉤子 / 配置 / 體檢 / 自動化）；一份人類可讀的能力總圖見 references/CAPABILITY_MAP.md（所有能力 + 一句話觸發 + 是否預設開，掃一眼就知道還能「整體保養」「配雲端同步」）。 3. 看結果：AI 回顯「已記 XX / 已找到 N 條 / 已配好」確認生效；召回後可能問「這條是否有用」，回 good/bad 即可（不想被問說「不用校準」）。 🎬 想要 AI 用「對話 + 圖」帶你過一遍功能 / 教學 / 配置？ 直接說「介紹一下這個記憶系統 / 教我怎麼用 / 工作流程」即可觸發 keeper-conversational-guide 對話式導覽（架構圖 + 生命週期圖 + 配置流程圖，邊看邊聊，不用通讀長文件）。它是本技能的「視覺化引子」，命令引數仍以本檔案與 references/COMMANDS.md 為準。

📦 開箱即用：裝完 skill 即獲得預設能力——儲存路徑 · 中文語義（fastembed，本地 ONNX） · 詞法兜底，不用手配就能記 / 找 / 整理。鉤子 / 守護程序 / 自動記憶需跑一次 keeper_setup.py all（或說"幫我一鍵配好"）才啟用——裝後跑 doctor 即可驗證是否就緒（詳見 §八）。 僅 3 項需手動開啟（安全/外部/重資源）：① 加密（忘 key = 資料永久丟失）② IMA 雲端同步（需外部知識庫）③ 本地 LLM/Ollama（~5GB）。

🗣️ 你說什麼 → AI 做什麼（高頻示例）

💡 高階 / 運維類能力也對 AI 說人話就能觸發（不用滾到下面長尾表也知道）：聚類「把相似的記憶聚成一類」、蒸餾「把相似記憶提煉成一條原則」、矛盾仲裁「看看有沒有重複矛盾」、批次歸檔「把老記憶批次歸檔」、體檢「給我出個記憶看板 / 看看庫的整體狀況」、圖譜「給記憶建個關係圖譜」——完整長尾觸發見下方「🗣️ 長尾高階操作 → 對 AI 說什麼」與 COOKBOOK.md §7/§8/§9。

🩺 出問題了？別翻文件。 直接對 AI 說"記不進去了 / 找不到了 / embedding 降級了 / 自動記沒生效 / 召回了已歸檔的記憶（或該召回的沒召回）"，AI 會跑 doctor+audit 讀真實狀態、定位原因、對話式引導你修，確認後再動手；若是"索引與檔案對不上"這類漂移，AI 會跑 doctor --fix 以檔案為準回填（詳見 references/QA.md §14）。QA.md / INSTALL 排錯段是給 AI 查的後臺索引，你無需通讀。 🗣️ 把技術報錯翻成普通話（AI 行為紅線）：任何命令返回 ok:false 或 Python 報錯，絕不直接把原始英文/內部常量（TIERS/SCENE_CANON/棧幀等）丟給使用者——先翻譯成一句大白話說明"出了什麼事 + 你下一步該說什麼/點什麼"，例如把 tier 必須是 (...) 說成「層級只能填 core/curated/active/archived 這幾個，你剛才填的不在裡頭」。報錯文案本身也已儘量人話化（見 references/CAPABILITY_MAP.md 末段"遇到問題怎麼辦"）。 ⚠️ 對話解決不了的邊界（設計使然，非缺陷）：① 加密 key 丟失 → 資料永久丟失，任何對話無法恢復（務必 recovery-code --write 出恢復碼兜底）；② 環境級故障（Python 缺失 / fastembed 下載失敗 / 計劃任務被系統策略停用）→ AI 能引導排查，但 OS 層改動需你手動處理。其餘記憶操作類問題（記不進、找不到、誤刪找回、同步異常等）均可對 AI 說人話解決。 其餘 40+ 記憶操作（備份/恢復/歸檔/刪除/回滾/關係鏈/輪換金鑰/恢復碼/校準/stats/explain/隔離複審等）均可通過自然語言觸發，AI 路由到 memory_ops.py（62 op）+ mem_bridge.py（29 通用橋接命令）。投資域專屬橋為 scripts/investment_bridge.py（seed/graph，與根 mem_bridge.py 是兩個不同檔案，勿混）。完整對映見 references/COMMANDS.md。

⚠️ mem_bridge 命令總數 = 29（inject / inject_stats / distill / rank / route / retrieve / capture / scan_dup / working / graph / guard / drift / seed / compress / coach / reflect / purge / promote / to-l2 / feedback / selftest / decay / recurrence / summary-index / tree-view / taxonomy / import / benchmark / mcp）。

⚠️ audit 同名異義（已在程式碼層消歧）：memory_ops 的 audit = 按庫規模推薦「該開哪些功能」；mem_bridge 原來也叫 audit、實為只讀掃描內部近重複/矛盾（I5），二者同名兩義、易踩坑。mem_bridge 側已更名為 audit → scan_dup，程式碼層根除碰撞；memory_ops audit 保持不變。mem_bridge 全部 29 個命令（inject/rank/route/retrieve/capture/guard/drift/seed/compress/coach/selftest/scan_dup/import/benchmark/mcp 等）的用途與引數見 references/MEM_BRIDGE.md。

🎬 實際體驗：你對 AI 說"幫我規劃記憶分類"，AI 會問你幾個問題，然後自動生成分類樹並生效。你說"關掉彈窗"，AI 改完設定告訴你"已切到 silent 模式 ✅，重啟後生效"。全程不用敲命令、不用看輸出。

⚠️ 關於鉤子彈窗（不是 bug）

在 full 模式下，你可能看到每點一次傳送按鈕，介面閃一下"執行中"提示條——這是 WorkBuddy 的鉤子執行指示器（平臺固有行為，非 keeper 問題），表示後臺在自動載入相關記憶注入上下文。切到 silent（預設）即無彈窗。詳見 references/QA.md「鉤子彈窗」。

切換方式：對 AI 說"關掉彈窗"（→ silent）或"恢復完整鉤子"（→ full）。改完後重啟 WorkBuddy 生效。模式持久化在 hooks_config.json，更新/重灌 skill 不會偷偷改回來。

4.2 四個執行時開關（口語可切）

①② 是"捕獲"（從哪來經驗）；③④ 是"質量"（校準 / 定期整理）。四個絕不刪除記憶。

4.3 可選能力開啟總覽

📊 先一眼分清「預設開 / 一句話開 / 需手動配」：絕大多數能力其實已預設開，只有 3 項需手動（加密 / IMA / Ollama）。完整「三桶分類」見 references/ENABLEMENT.md——它逐條告訴你哪些不用管、哪些一句話開、哪些必須配。不想讀長文？直接問 AI「我還能開哪些功能」跑只讀 audit 即可。

下面都是可選能力，按"獲得什麼 / 代價"一句話概括（詳細原理與邊界見 references/FEATURES.md）：

• 神經語義召回（中文更強，預設已開） — fastembed（本地 ONNX，CPU 推理）開箱預設啟用，首次用到中文語義時自動安裝+下載（約 90MB ONNX 模型權重，落盤於 ~/.workbuddy/cache/agent-local-memory-keeper/models，與 skill 包分離、重灌不丟），中文改寫召回率 ~30%→90%+。實測端到端 recall ≈ 3.75s（新查詢，模型冷載入佔 ~78%/約 2.9s）；開啟磁碟快取（預設已開）後重複查詢冷 CLI 降至 ~0.9s；啟用守護程序後模型常駐、召回降至毫秒級（詳見 §4.5 / references/COOKBOOK.md 守護程序）。記憶體 ≤8GB 老機器可降級 embed lexical 或 記憶 --flat。
• ANN 加速 — 無需裝，庫 ≥50 條且 ≤256 條預設自動啟用（結果與全量一致，500 條實測 8 倍加速）；>256 條大庫剪枝需顯式 recall --ann；<50 條不啟用（反而慢）。
• 聚類 / 主題標籤 — 需神經後端 + 庫 ≥8 條已嵌入；cluster --apply 偶爾跑。
• 視覺化 Dashboard — dashboard 生成單檔案 HTML，秒級。
• 主動矛盾 / 重複掃描 — doctor --contradictions（需神經後端）；分桶後開銷近似線性（僅同簇/同標籤/同品牌內兩兩比對，大庫自動跳過 subject 桶），仍吃 CPU，推薦每週跑一次低頻。
• 加密 at rest — 設 AI_MEM_ENCRYPTION_KEY；忘 key = 永久丟失，務必 recovery-code --write 出恢復碼。有敏感內容強烈推薦。
• 本地 LLM 增強（Ollama） — 需裝 Ollama + 拉模型（~5GB，常駐吃記憶體/磁碟/GPU）；僅本機夠強才開，低配機器勿開。
• IMA 知識庫映象 — 歸檔記憶自動推送到 IMA 知識庫（需在已連 IMA MCP 的會話裡配），跨工具/跨會話共享沉澱；代價：需先配 IMA 知識庫，且推送前強制脫敏（紅線，絕不交付明文）。
• 行為規則層固化（export-rules） — 把高頻/已確認經驗固化成 AI 每輪行為規則寫入 AGENTS.md，讓記憶直接改變行為而非僅被 recall 命中；代價：手動觸發，規則寫進專案/使用者 AGENTS.md（可提交 git）。
• 輕量檔案層（--flat） — 跳過 SQLite/LLM，全部落純 Markdown、grep 召回，零依賴；代價：失去語義召回/分層等高階能力，適合只"記個小坑"的極簡使用者。
• about_axis 四軸 / 複述加權 / recurrence 候選 / staging 隔離開關 / freshness 過濾 — 預設即開，無需配置。
• 從歷史會話主動沉澱（conversation_search → harvest --from-conversations） — 把 WorkBuddy 雲端/歷史會話裡"值得長期記的"經驗批次沉澱進 keeper：AI 先 conversation_search 按回溯視窗（預設 30 天）檢索歷史會話 → 整理為文本檔案 → harvest --from-conversations --session <file> 沉積。會話來源記憶打 wb_session 標籤並做冪等去重（同一段歷史會話重複跑不會重複沉積、不會回聲）。代價：需在 WB 會話中由 AI 編排（CLI 不聯網），本質是"WB 雲記憶 → keeper 語義庫"的橋。

4.4 推薦開啟配置（按場景）

• 個人小庫 / 中文使用者（<50 條）：中文語義已預設開（無需動作）；ANN 關；有敏感內容就開 加密；其餘保持關。
• 中-大庫（≥50 條）：加開 ANN；doctor --contradictions 放進每週自動化跑一次；cluster 偶爾手動。
• 有本地 Ollama 且機器夠強：可加開 LLM 增強。
• 不確定開哪些 / 不知道能讓你做什麼：隨時說"幫我看看我能開哪些功能" → AI 跑只讀 audit 給建議；或直接問"你能幫我管理記憶系統做哪些事" → AI 列出全部能力。

🔍 配置體檢速查（按有益度）

下面這些 audit 會評估的常見可開啟項。若你還沒開，直接對 AI 說對應話術即可開啟；已開的不會出現在此提醒裡。audit 會按你庫規模/環境給最終建議。

🔴 IMA 紅線：推送前強制脫敏，命中任何真實路徑/憑證會直接報錯退出，絕不交付明文。脫敏邏輯見 scripts/_keeper_ima_push.py。

4.5 ⚡ 效能消耗提醒（低配 / 老機器必讀）

keeper 預設很輕：silent 鉤子 + 詞法兜底，幾乎零資源。但下面幾項會持續或顯著吃資源——記憶體 ≤8GB、老 CPU、無獨顯的機器請看清再開，或改用替代方案：

🔴 鐵律：低配機器不要開 Ollama；fastembed 可降級為詞法；doctor --contradictions 與 cluster 只放低頻任務。上面這些不會偷偷吃資源——都是你明確開了才跑。

🛡️ 矛盾仲裁安全鐵律（離線禁寫）：doctor --arbitrate 在未注入 LLM 時禁止真實仲裁——不注入 LLM 跑非 --dry-run 會直接拒絕、零寫入，僅 --dry-run 可預覽候選；注入 KEEPER_LLM_* 後，仲裁對每對強矛盾候選強制讓 LLM 確認"真矛盾（互斥）"，非矛盾一律跳過，絕不誤標舊真實記憶。完整三重防誤殺門與審計欄位見 references/LIMITS.md §仲裁。

五、有哪些要求（前置條件）

• 必需要：一個能跑 Python 的執行環境（用來執行 scripts/memory_ops/__init__.py）。
• 開箱即用（零配置）：裝完 skill 即獲得中文語義召回（fastembed 輕量本地 ONNX，首次用到時自動安裝+下載一次，之後完全離線）+ silent 鉤子（無彈窗） + 詞法兜底，不用手配任何東西就能記 / 找 / 整理。
• 按需手動開啟（僅這 3 項，因安全/外部/重資源而非常規預設）：
• cryptography + 加密開關 — 落盤加密（影響：忘 key = 資料永久丟失，預設不開啟）。
• Ollama + 模型（~5GB）— 本地 LLM 增強（重，僅本機夠強才開）。
• IMA 知識庫 — 跨工具雲端映象（需先在已連 IMA MCP 的會話裡配知識庫）。
• 網路：預設純本地、零雲端；僅"首次自動裝 fastembed"需聯網一次（HF 不可達自動切國內映象），之後完全離線。加密/本地LLM/IMA 按需另聯網。

裝到哪個 Python、怎麼驗證、裝不上怎麼辦 —— 見 references/INSTALL.md。

六、如何配置

一句話：對 AI 說即可，AI 背後跑 keeper_setup.py，你不用手敲任何環境變數（詳見 references/TUTORIAL.md §0.5 與 references/COOKBOOK.md）。

你可能手設的只有兩個環境變數： - AI_MEMORY_STORE — 記憶庫根目錄（預設 D:/AI記憶 或 ~/.ai-memory；換路徑/跨裝置攜帶時設）。 - AI_MEM_ENCRYPTION_KEY — 開啟加密（忘 key = 資料永久丟失，絕不寫進檔案/git；用 recovery-code --write 出可手抄恢復碼）。

其餘執行時開關（inject / feedback / embed 後端 / ANN 閾值等）由 AI 在對話裡按你要求調，或收口在 store/config.json 的 keeper 塊。

七、如何使用（最小上手）

記憶預設零配置路徑，首次自動建庫。想照著跑一遍看每步輸出，跑 python scripts/demo_walkthrough.py。

最省事：日常直接對 AI 說「記一下… / 找一下之前那個… / 整理今天記的」，AI 背後自動調對應命令。

🧹 「整理」什麼時候跑、跑完怎麼算正常（不用讀文件也能懂）： - 何時自動整理：① 會話結束（Stop 鉤子，預設開、零配置，你不用管）；② 你手動說"幫我整理今天記的 / 整理一下"；③ 周維護自動化鐵律不含 reflect——只做採集 + 聚類 + 矛盾修復 + 沉底 + IMA，絕不刪除或改動記憶。 - 跑完你會看到什麼（成功標準）：reflect --auto 輸出類似「去重 N 條 / 糾錯 M 條 / 晉升 K 條 / 歸檔 P 條」，永遠 0 刪除（它只去重·糾錯·晉升·歸檔，絕不碰 active 記憶）；歸檔的記憶沉到 memories/archive/，隨時 recall --deep 找回。 - 怎麼算"不正常"：若看到大量「刪除」或記憶憑空消失，那不是 reflect 乾的（它不刪），大機率是手動 delete --yes 或 purge --apply——去本檔案「四條不可破紅線」核對。

🤝 對話契約（你來我往長這樣）： - 你說一句，AI 背後跑命令並回顯「已設 XX / 已記 XX」——你不用懂命令、不用看輸出也能確認生效。 - 召回後 AI 可能問「這條是否有用？」，回 good / bad 即完成校準（每會話上限 3 次防過載）；不想被問就說「不用校準」。 - 開了 converse / harvest 後，AI 會在對話裡靜默沉澱經驗，不必你每次主動說"記一下"。 - 若 AI 陷入"再確認"迴圈，說「不用校準 / 不用注入」即可切斷。 完整的對話來回樣例見 references/TUTORIAL.md。

照跑三條（純命令列，不依賴 AI）：

python scripts/memory_ops/__init__.py init                                   # 首次建庫（可省，首次 deposit 自動建）
python scripts/memory_ops/__init__.py deposit --category best_practice --summary "一句話經驗"
python scripts/memory_ops/__init__.py recall --query "你想問的事"

常見場景一句話：記經驗 deposit ｜ 找經驗 recall --query ｜ 糾正舊結論 deposit --category correction --corrects <舊id>（舊記憶自動 superseded）｜ 整理 reflect --auto ｜ 定期降權 decay --apply（大庫 decay --apply --incremental）｜ 標核心 promote --tier core ｜ 關聯兩條 link --rel see_also --target <id> ｜ 刪（可找回先 archive，真刪必須 delete --yes）｜ 看開了哪些功能 audit ｜ 召回分佈 stats ｜ 看單條為什麼被召回 explain --id <id> ｜ 匯出 export --format md ｜ 輪換加密金鑰 rekey --new-key "<新金鑰>" ｜ 撤銷自動重分類 reflect --undo ｜ 脫離 WorkBuddy 自排程 schedule_self_heal --cron ｜ 一鍵統一自治迴圈 self-heal [--force]（合併 reflect/evolve/decay/doctor/skill-sync/export-rules）。

完整分步教程（含真實返回樣例）見 references/TUTORIAL.md；所有命令與引數見 references/COMMANDS.md。

八、如何檢查可以開啟哪些功能（自檢清單）★

不確定自己該開哪些能力、或想確認裝好沒有？兩條只讀命令，不改動任何資料：

• audit（能力體檢，純只讀） — 按你庫規模 / 環境給每個可選功能的"開啟 / 關閉"建議，並標出當前已開/未開。一句話問 AI："幫我看看我能開哪些功能"，AI 跑 audit 後給建議清單。 bash python scripts/memory_ops/__init__.py audit
• doctor（就緒綠紅自檢） — 七項一鍵體檢：儲存根 / 中文語義 / 落盤加密 / 鉤子註冊 / 守護程序 / IMA 同步 / 召回冒煙，綠紅表一眼看懂"裝好沒"；庫內深查另檢索引↔檔案一致性、孤兒條目、--flat 分割槽（如有 flat 條目會提示其不在主庫召回）。 bash python scripts/keeper_setup.py doctor # 裝後就緒自檢（推薦） python scripts/memory_ops/__init__.py doctor # 庫內健康深查（索引/關係一致性） python scripts/memory_ops/__init__.py doctor --fix # 自檢後一鍵修復：回填三態漂移（檔案↔索引內容不同步）+ 剪枝懸空關係 + 移除無檔案索引條目，不刪記憶內容

區別一句話：audit 回答"該開哪些"，doctor 回答"裝好沒 / 庫健康嗎"。doctor 只讀不寫，doctor --fix 才寫修（不刪內容）。--contradictions 做對立記憶對檢測（需神經後端）。

九、安全護欄（必讀·精簡）

🔴 四條不可破紅線（無論你怎麼說，AI 都守）： 1. 絕不批次硬刪：reflect / archive / decay 只做去重·糾錯·歸檔（軟保留，檔案永在、recall --deep 可找回）；唯一真刪是顯式 delete --yes，且單次單條。 2. 刪必須顯式 --yes：不帶 --yes 的刪除一律被拒、檔案原樣保留（防「以為刪了」的影子狀態）。 3. 重要記憶分類強制：importance ≥ 0.7 且某軸被低置信自動分類時，系統標 classify_review 並告警——不會靜默猜分；非法值直接報錯（不偷偷改）。 4. IMA 明文庫強制脫敏：推送前自動 strip 憑證 / 真實路徑 / 郵箱，脫敏後還複檢一遍；任何殘留直接失敗退出，絕不交付明文。

防 AI 反覆確認死迴圈：預設 feedback 每會話 3 次 + inject 每會話 6 次雙閘門；若 AI 陷入"再確認"開放回路，對 AI 說"不用校準 / 不用注入"即可切斷，或設 KEEPER_FEEDBACK_SESSION_CAP=0。詳見 references/LIMITS.md §7 與 references/QA.md。

全部限制 / 紅線 / 反模式 / 避坑速查 —— 見下方「📌 反模式清單」「🕒 高階功能：何時呼叫」與 references/LIMITS.md、references/QA.md。

📌 反模式清單（❌ 錯誤做法 → ✅ 正確做法）

想避坑看這一處就夠了（單一真源）。每條都對應上面紅線或下面的限制，不要多處翻。

🕒 高階功能：何時呼叫（限制速查）

高階能力不是"常開更好"，按庫規模/機器實況取捨。詳細原理見 references/FEATURES.md / references/LIMITS.md。

投資記憶能力圈（investment 域）

keeper 原生支援 investment 域，把「量化投資回測」做成體系化記憶：資料/引數 → 因子 → 因子測試 → 組合系統，四層物件全記住、能關聯、可回溯。完整模型、型別化關聯、4 層建記憶模板、召回路由與排障見 references/INVESTMENT.md。

• ⚠️ 冷啟動用對橋：投資記憶冷啟動請用投資專屬橋 python scripts/investment_bridge.py seed --domain investment；根 mem_bridge.py seed --domain 量化 已廢棄（量化域統一為 investment）。雙橋區別見上文「AI 路由」段與 references/COMMANDS.md。
• ⚠️ 投資記憶走「記 + 驗 + 明確待校驗」閉環，避免只記不驗：投資記憶能用 verify-investment 從 DuckDB 復算數值做回檢——verify-investment --duckdb <路徑> --sql-map <json>，每條 metric 對應一條返回單值的 SQL，庫算出的值與記憶裡記的值不符會標 verified=False 並下調信念強度留在待複核。校驗結果明確區分三種結局——verified_true/false（已復算）、skipped（已就緒但本記憶指標無可用 SQL，正常無需復算）、needs_setup（記憶本應校驗卻因缺 DuckDB/sql_map/DuckDB 不可用而條件缺失未校驗）；存在 needs_setup 時返回附帶 default_sql_map_template + setup_hint 引導 bootstrap。庫完全不可用時仍 fail-open（只告警不阻塞，絕不誤判真結論為假）。詳見 references/EVOLUTION.md §校驗。

十、深入閱讀（專業文件指引）

概述到此為止。下面這些專業文件才是細節與深讀的歸宿，按需取用：

開發者 / 維護者內部參考（普通使用者無需看，歸集在 references/_design/）：測試協議與"結論先取證"鐵律見 references/_design/DEV_TESTING.md；設計稿見 references/_design/。

常見問題（精簡 6 條，其餘見 references/QA.md）

• 誤刪了能恢復嗎？ 能。versions --id <id> → rollback --to-version N --yes；或 backup/restore 整庫 ZIP。刪除前優先用 archive（沉底可找回）。
• reflect 會刪我的記憶嗎？ 不會。只做去重/糾錯/晉升/歸檔，絕不刪除 active 記憶；遺忘路徑是 decay 降權 + reflect --auto 歸檔（可 recall --deep 找回）。
• 中文換個說法搜不到？ 預設詞法對深度改寫弱——裝 fastembed 開真語義（~30%→90%+），或走線上 embeddings。裝後 report 確認後端。
• 需要聯網嗎？ 預設純本地零雲端；僅首次裝 fastembed / 可選 Ollama 需聯網一次。

  7w4.net小蔥技能。

• 記憶存在哪 / 怎麼備份？ 預設 D:/AI記憶 或 ~/.ai-memory；backup 匯出 ZIP、restore 恢復；memories/ 可直接複製遷移。
• AI 反覆"再確認"死迴圈？ 說"不用校準 / 不用注入"，或設 KEEPER_FEEDBACK_SESSION_CAP=0 全關。

質量上乘——文件結構清晰易懂，裝完即用不用配置，對中文支援很好，敏感資訊安全機制做得很到位。記憶的去重、糾錯、分層、召回等核心功能完整，自動化能力（鉤子、守護程序、排程）開箱可用。唯一需要注意的是加密功能一旦開啟就必須妥善保管金鑰，否則資料無法恢復——但這是安全設計的權衡取捨，不算缺陷。總體來說這是一個功能完善、體驗友好、安全意識強的記憶管理工具。