🌐 這是自動翻譯。歡迎社群貢獻修正！ ---


Claude-Mem

🇨🇳 中文 • 🇹🇼 繁體中文 • 🇯🇵 日本語 • 🇧🇷 Português • 🇰🇷 한국어 • 🇪🇸 Español • 🇩🇪 Deutsch • 🇫🇷 Français 🇮🇱 עברית • 🇸🇦 العربية • 🇷🇺 Русский • 🇵🇱 Polski • 🇨🇿 Čeština • 🇳🇱 Nederlands • 🇹🇷 Türkçe • 🇺🇦 Українська • 🇻🇳 Tiếng Việt • 🇮🇩 Indonesia • 🇹🇭 ไทย • 🇮🇳 हिन्दी • 🇧🇩 বাংলা • 🇷🇴 Română • 🇸🇪 Svenska • 🇮🇹 Italiano • 🇬🇷 Ελληνικά • 🇭🇺 Magyar • 🇫🇮 Suomi • 🇩🇰 Dansk • 🇳🇴 Norsk

為 Claude Code 打造的持久記憶壓縮系統

License Version Node Mentioned in Awesome Claude Code

thedotmack/claude-mem | Trendshift


Claude-Mem Preview

快速開始 • 運作原理 • 搜尋工具 • 文件 • 設定 • 疑難排解 • 授權條款

Claude-Mem 透過自動擷取工具使用觀察、產生語意摘要並在未來的工作階段中提供使用，無縫保留跨工作階段的脈絡。這使 Claude 即使在工作階段結束或重新連線後，仍能維持對專案的知識連續性。

--- ## 快速開始 在終端機中開啟新的 Claude Code 工作階段，並輸入以下指令： ``` > /plugin marketplace add thedotmack/claude-mem > /plugin install claude-mem ``` 重新啟動 Claude Code。先前工作階段的脈絡將自動出現在新的工作階段中。 ### Pi-Agent（pi-mono） 將 claude-mem 安裝為 [pi-agents](https://github.com/badlogic/pi-mono) 的持久記憶擴充功能： ```bash pi install npm:pi-agent-memory ``` 為任何基於 pi-mono 的代理（pi-coding-agent、OpenClaw、自訂執行環境）提供跨工作階段的記憶功能。觀察結果會在同一資料庫中的所有引擎之間共享。完整說明請參閱 [pi-agent README](../pi-agent/README.md)。 **主要功能：** - 🧠 **持久記憶** - 脈絡跨工作階段保留 - 📊 **漸進式揭露** - 具有 Token 成本可見性的分層記憶擷取 - 🔍 **技能式搜尋** - 使用 mem-search 技能查詢專案歷史 - 🖥️ **網頁檢視介面** - 在 http://localhost:37777 即時檢視記憶串流 - 💻 **Claude Desktop 技能** - 從 Claude Desktop 對話中搜尋記憶 - 🔒 **隱私控制** - 使用 `` 標籤排除敏感內容的儲存 - ⚙️ **脈絡設定** - 精細控制注入哪些脈絡 - 🤖 **自動運作** - 無需手動介入 - 🔗 **引用** - 使用 ID 參考過去的觀察（透過 http://localhost:37777/api/observation/{id} 存取，或在 http://localhost:37777 的網頁檢視器中檢視全部） - 🧪 **Beta 通道** - 透過版本切換試用 Endless Mode 等實驗性功能 --- ## 文件 📚 **[檢視完整文件](docs/)** - 在 GitHub 上瀏覽 Markdown 文件 ### 入門指南 - **[安裝指南](https://docs.claude-mem.ai/installation)** - 快速開始與進階安裝 - **[使用指南](https://docs.claude-mem.ai/usage/getting-started)** - Claude-Mem 如何自動運作 - **[搜尋工具](https://docs.claude-mem.ai/usage/search-tools)** - 使用自然語言查詢專案歷史 - **[Beta 功能](https://docs.claude-mem.ai/beta-features)** - 試用 Endless Mode 等實驗性功能 ### 最佳實務 - **[脈絡工程](https://docs.claude-mem.ai/context-engineering)** - AI 代理脈絡最佳化原則 - **[漸進式揭露](https://docs.claude-mem.ai/progressive-disclosure)** - Claude-Mem 脈絡啟動策略背後的理念 ### 架構 - **[概覽](https://docs.claude-mem.ai/architecture/overview)** - 系統元件與資料流程 - **[架構演進](https://docs.claude-mem.ai/architecture-evolution)** - 從 v3 到 v5 的旅程 - **[Hooks 架構](https://docs.claude-mem.ai/hooks-architecture)** - Claude-Mem 如何使用生命週期掛鉤 - **[Hooks 參考](https://docs.claude-mem.ai/architecture/hooks)** - 7 個掛鉤腳本說明 - **[Worker 服務](https://docs.claude-mem.ai/architecture/worker-service)** - HTTP API 與 Bun 管理 - **[資料庫](https://docs.claude-mem.ai/architecture/database)** - SQLite 結構描述與 FTS5 搜尋 - **[搜尋架構](https://docs.claude-mem.ai/architecture/search-architecture)** - 使用 Chroma 向量資料庫的混合搜尋 ### 設定與開發 - **[設定](https://docs.claude-mem.ai/configuration)** - 環境變數與設定 - **[開發](https://docs.claude-mem.ai/development)** - 建置、測試、貢獻 - **[疑難排解](https://docs.claude-mem.ai/troubleshooting)** - 常見問題與解決方案 --- ## 運作原理 **核心元件：** 1. **5 個生命週期掛鉤** - SessionStart、UserPromptSubmit、PostToolUse、Stop、SessionEnd（6 個掛鉤腳本） 2. **智慧安裝** - 快取的相依性檢查器（pre-hook 腳本，非生命週期掛鉤） 3. **Worker 服務** - 連接埠 37777 上的 HTTP API，含網頁檢視介面與 10 個搜尋端點，由 Bun 管理 4. **SQLite 資料庫** - 儲存工作階段、觀察、摘要 5. **mem-search 技能** - 具有漸進式揭露的自然語言查詢 6. **Chroma 向量資料庫** - 用於智慧脈絡擷取的混合語意 + 關鍵字搜尋 詳情請參閱[架構概覽](https://docs.claude-mem.ai/architecture/overview)。 --- ## MCP 搜尋工具 Claude-Mem 透過遵循 Token 高效的 **3 層工作流程模式**，以 **4 個 MCP 工具**提供智慧記憶搜尋： **3 層工作流程：** 1. **`search`** - 取得精簡索引與 ID（每筆結果約 50-100 tokens） 2. **`timeline`** - 取得有趣結果周圍的時間脈絡 3. **`get_observations`** - 僅為過濾後的 ID 擷取完整詳情（每筆結果約 500-1,000 tokens） **運作方式：** - Claude 使用 MCP 工具搜尋您的記憶 - 從 `search` 開始取得結果索引 - 使用 `timeline` 檢視特定觀察周圍發生的事情 - 使用 `get_observations` 擷取相關 ID 的完整詳情 - 透過在擷取詳情前過濾，**節省約 10 倍 token** **可用的 MCP 工具：** 1. **`search`** - 使用全文查詢搜尋記憶索引，依類型/日期/專案過濾 2. **`timeline`** - 取得特定觀察或查詢周圍的時間脈絡 3. **`get_observations`** - 依 ID 擷取完整觀察詳情（批次處理多個 ID） 4. **`__IMPORTANT`** - 工作流程文件（Claude 永遠可見） **使用範例：** ```typescript // 步驟 1：搜尋索引 search(query="authentication bug", type="bugfix", limit=10) // 步驟 2：檢閱索引，識別相關 ID（例如 #123、#456） // 步驟 3：擷取完整詳情 get_observations(ids=[123, 456]) ``` 詳細範例請參閱[搜尋工具指南](https://docs.claude-mem.ai/usage/search-tools)。 --- ## Beta 功能 Claude-Mem 提供具有實驗性功能的 **Beta 通道**，例如 **Endless Mode**（用於延長工作階段的仿生記憶架構）。在 http://localhost:37777 → Settings 的網頁檢視介面中切換穩定版與 Beta 版。 有關 Endless Mode 與如何試用的詳情，請參閱 **[Beta 功能文件](https://docs.claude-mem.ai/beta-features)**。 --- ## 系統需求 - **Node.js**：18.0.0 或更高版本 - **Claude Code**：具有外掛支援的最新版本 - **Bun**：JavaScript 執行環境與程序管理員（如缺少將自動安裝） - **uv**：用於向量搜尋的 Python 套件管理員（如缺少將自動安裝） - **SQLite 3**：用於持久儲存（已內建） --- ## 設定 設定在 `~/.claude-mem/settings.json` 中管理（首次執行時自動以預設值建立）。設定 AI 模型、Worker 連接埠、資料目錄、日誌層級與脈絡注入設定。 所有可用設定與範例請參閱 **[設定指南](https://docs.claude-mem.ai/configuration)**。 --- ## 開發 建置說明、測試與貢獻工作流程請參閱 **[開發指南](https://docs.claude-mem.ai/development)**。 --- ## 疑難排解 如遇問題，向 Claude 描述問題，troubleshoot 技能將自動診斷並提供修正。 常見問題與解決方案請參閱 **[疑難排解指南](https://docs.claude-mem.ai/troubleshooting)**。 --- ## 錯誤回報 使用自動產生器建立完整的錯誤回報： ```bash cd ~/.claude/plugins/marketplaces/thedotmack npm run bug-report ``` ## 貢獻 歡迎貢獻！請依照以下步驟： 1. Fork 儲存庫 2. 建立功能分支 3. 加入測試並進行變更 4. 更新文件 5. 提交 Pull Request 貢獻工作流程請參閱[開發指南](https://docs.claude-mem.ai/development)。 --- ## 授權條款 本專案採用 **GNU Affero 通用公共授權條款 v3.0**（AGPL-3.0）授權。 Copyright (C) 2025 Alex Newman (@thedotmack). All rights reserved. 完整詳情請參閱 [LICENSE](LICENSE) 檔案。 **這代表什麼：** - 您可以自由使用、修改與散佈此軟體 - 如果您修改並部署於網路伺服器上，您必須公開您的原始碼 - 衍生作品也必須採用 AGPL-3.0 授權 - 本軟體不提供任何擔保 **關於 Ragtime 的說明**：`ragtime/` 目錄採用 **PolyForm Noncommercial License 1.0.0** 另行授權。詳情請參閱 [ragtime/LICENSE](ragtime/LICENSE)。 --- ## 支援 - **文件**：[docs/](docs/) - **Issues**：[GitHub Issues](https://github.com/thedotmack/claude-mem/issues) - **儲存庫**：[github.com/thedotmack/claude-mem](https://github.com/thedotmack/claude-mem) - **官方 X 帳號**：[@Claude_Memory](https://x.com/Claude_Memory) - **官方 Discord**：[加入 Discord](https://discord.com/invite/J4wttp9vDu) - **作者**：Alex Newman ([@thedotmack](https://github.com/thedotmack)) --- **使用 Claude Agent SDK 建置** | **由 Claude Code 驅動** | **以 TypeScript 開發**