Alex Newman
36b0929fae
* Add server beta runtime foundation * Address server beta review findings * Resolve server beta review comments * Tighten server beta review follow-ups * Harden server beta auth and search * Avoid unnecessary FTS rebuilds * Block scoped keys from creating projects * Release BullMQ claims best effort on close * Address server beta review blockers * Reset BullMQ claims best effort * Add Postgres observation storage foundation * feat(server-beta): add independent runtime service Introduce src/server/runtime/ as a self-contained server-beta runtime that owns its lifecycle, Postgres bootstrap, and HTTP boundary without depending on WorkerService. ServerBetaService wraps the existing Server class, exposes /healthz and /v1/info with runtime="server-beta", and persists state to dedicated paths (.server-beta.pid|.port|.runtime.json). The four boundary managers (queue, generation worker, provider registry, event broadcaster) are intentionally disabled in this phase and report their status through /v1/info; later phases activate them. Adds plans/2026-05-07-finish-bullmq-branch-ship-plan.md to track the remaining work for this branch. Phase 2 of plans/2026-05-07-server-beta-independent-bullmq-observation-runtime.md. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(server-beta): route CLI lifecycle and bundle separate runtime scripts/build-hooks.js now produces plugin/scripts/server-beta-service.cjs as a separate Node CJS bundle, alongside the existing worker-service bundle. The server-beta runtime is now installable independently. src/npx-cli/commands/server.ts routes start|stop|restart|status to the server-beta lifecycle instead of the legacy worker. The worker keeps its own start|stop|restart|status under the worker namespace; the two runtimes can be operated independently. src/services/worker-service.ts adds a server-* command parser branch that delegates to the sibling server-beta-service.cjs bundle so direct worker-service invocations still route to the right runtime. tests/npx-cli-server-namespace.test.ts updated to expect server-beta lifecycle routing. Includes rebuilt plugin/scripts/*.cjs bundles produced by build-and-sync. Phase 2 of plans/2026-05-07-server-beta-independent-bullmq-observation-runtime.md. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(server-beta): add BullMQ job queue primitives Introduce src/server/jobs/ as the queue-side primitives that Phase 3 of the server-beta runtime needs to operate. types.ts defines a discriminated union over the four job kinds (event, event-batch, summary, reindex) and maps each to a per-kind BullMQ queue name and deterministic-ID prefix. job-id.ts builds deterministic, colon-free BullMQ jobIds from (kind, team, project, source). The colon ban exists because BullMQ uses ':' as a Redis key separator internally; embedding ':' in jobIds breaks scan and state lookups. ServerJobQueue.ts is a thin wrapper over BullMQ Queue + Worker that enforces autorun:false, default concurrency 1, and an attached error listener — all per BullMQ docs requirements. Test seams accept queue and worker factories so unit tests do not need Redis. outbox.ts publishes through the Postgres ObservationGenerationJob repository as canonical history. enqueueOutbox writes the row first, then publishes to BullMQ; if BullMQ throws, the row is transitioned to failed and a failed event is appended. reconcileOnStartup re-enqueues queued + processing rows after a restart, replacing terminal BullMQ jobs that may still be holding the deterministic ID slot. markCompleted and markFailed wrap transitionStatus and append the matching event row. Includes 20 unit tests covering deterministic ID stability, colon-free output, queue lifecycle, error-listener attachment, double-start refusal, idempotent enqueue, BullMQ failure rollback, startup reconciliation, max-attempts skipping, and completion / failure / retry transitions. Phase 3 commit 1 of plans/2026-05-07-server-beta-independent-bullmq-observation-runtime.md. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(server-beta): activate queue boundary in runtime service Wire ActiveServerBetaQueueManager into the server-beta runtime graph. The active manager owns one ServerJobQueue per generation kind (event, event-batch, summary, reindex) and surfaces lane metadata through boundary health. Selection is opt-in and fail-fast: if CLAUDE_MEM_QUEUE_ENGINE is set to bullmq the active manager is constructed (and any Redis/config error throws — no silent fallback to SQLite, per Phase 3 anti-pattern guard). For any other engine the disabled boundary remains so worker-era and test setups stay compatible. Widens ServerBetaBoundaryHealth.status to a discriminated union ('disabled' | 'active' | 'errored') with optional details. The disabled adapter still emits status='disabled', which keeps the existing server-beta-service test green. ServerBetaService receives the manager through a new optional queueManager field on CreateServerBetaServiceOptions so test graphs and Phase 4 wiring can inject custom managers. Adds tests/server/runtime/active-queue-manager.test.ts covering bullmq guard, active health shape, per-kind queue access, close behavior, and post-close errored health. Phase 3 commit 2 of plans/2026-05-07-server-beta-independent-bullmq-observation-runtime.md. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix(server-beta): cap /v1/events/batch at 500 events Prevents unbounded array DoS surface flagged in PR review. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
308 lines
12 KiB
Markdown
308 lines
12 KiB
Markdown
🌐 這是自動翻譯。歡迎社群貢獻修正！
|
||
|
||
---
|
||
<h1 align="center">
|
||
<br>
|
||
<a href="https://github.com/thedotmack/claude-mem">
|
||
<picture>
|
||
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-dark-mode.webp">
|
||
<source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-light-mode.webp">
|
||
<img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/claude-mem-logo-for-light-mode.webp" alt="Claude-Mem" width="400">
|
||
</picture>
|
||
</a>
|
||
<br>
|
||
</h1>
|
||
|
||
<p align="center">
|
||
<a href="README.zh.md">🇨🇳 中文</a> •
|
||
<a href="README.zh-tw.md">🇹🇼 繁體中文</a> •
|
||
<a href="README.ja.md">🇯🇵 日本語</a> •
|
||
<a href="README.pt-br.md">🇧🇷 Português</a> •
|
||
<a href="README.ko.md">🇰🇷 한국어</a> •
|
||
<a href="README.es.md">🇪🇸 Español</a> •
|
||
<a href="README.de.md">🇩🇪 Deutsch</a> •
|
||
<a href="README.fr.md">🇫🇷 Français</a>
|
||
<a href="README.he.md">🇮🇱 עברית</a> •
|
||
<a href="README.ar.md">🇸🇦 العربية</a> •
|
||
<a href="README.ru.md">🇷🇺 Русский</a> •
|
||
<a href="README.pl.md">🇵🇱 Polski</a> •
|
||
<a href="README.cs.md">🇨🇿 Čeština</a> •
|
||
<a href="README.nl.md">🇳🇱 Nederlands</a> •
|
||
<a href="README.tr.md">🇹🇷 Türkçe</a> •
|
||
<a href="README.uk.md">🇺🇦 Українська</a> •
|
||
<a href="README.vi.md">🇻🇳 Tiếng Việt</a> •
|
||
<a href="README.id.md">🇮🇩 Indonesia</a> •
|
||
<a href="README.th.md">🇹🇭 ไทย</a> •
|
||
<a href="README.hi.md">🇮🇳 हिन्दी</a> •
|
||
<a href="README.bn.md">🇧🇩 বাংলা</a> •
|
||
<a href="README.ro.md">🇷🇴 Română</a> •
|
||
<a href="README.sv.md">🇸🇪 Svenska</a> •
|
||
<a href="README.it.md">🇮🇹 Italiano</a> •
|
||
<a href="README.el.md">🇬🇷 Ελληνικά</a> •
|
||
<a href="README.hu.md">🇭🇺 Magyar</a> •
|
||
<a href="README.fi.md">🇫🇮 Suomi</a> •
|
||
<a href="README.da.md">🇩🇰 Dansk</a> •
|
||
<a href="README.no.md">🇳🇴 Norsk</a>
|
||
</p>
|
||
|
||
<h4 align="center">為 <a href="https://claude.com/claude-code" target="_blank">Claude Code</a> 打造的持久記憶壓縮系統</h4>
|
||
|
||
<p align="center">
|
||
<a href="LICENSE">
|
||
<img src="https://img.shields.io/badge/License-Apache--2.0-blue.svg" alt="License">
|
||
</a>
|
||
<a href="package.json">
|
||
<img src="https://img.shields.io/badge/version-6.5.0-green.svg" alt="Version">
|
||
</a>
|
||
<a href="package.json">
|
||
<img src="https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg" alt="Node">
|
||
</a>
|
||
<a href="https://github.com/thedotmack/awesome-claude-code">
|
||
<img src="https://awesome.re/mentioned-badge.svg" alt="Mentioned in Awesome Claude Code">
|
||
</a>
|
||
</p>
|
||
|
||
<p align="center">
|
||
<a href="https://trendshift.io/repositories/15496" target="_blank">
|
||
<picture>
|
||
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge-dark.svg">
|
||
<source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge.svg">
|
||
<img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/trendshift-badge.svg" alt="thedotmack/claude-mem | Trendshift" width="250" height="55"/>
|
||
</picture>
|
||
</a>
|
||
</p>
|
||
|
||
<br>
|
||
|
||
<p align="center">
|
||
<a href="https://github.com/thedotmack/claude-mem">
|
||
<picture>
|
||
<img src="https://raw.githubusercontent.com/thedotmack/claude-mem/main/docs/public/cm-preview.gif" alt="Claude-Mem Preview" width="800">
|
||
</picture>
|
||
</a>
|
||
</p>
|
||
|
||
<p align="center">
|
||
<a href="#快速開始">快速開始</a> •
|
||
<a href="#運作原理">運作原理</a> •
|
||
<a href="#mcp-搜尋工具">搜尋工具</a> •
|
||
<a href="#文件">文件</a> •
|
||
<a href="#設定">設定</a> •
|
||
<a href="#疑難排解">疑難排解</a> •
|
||
<a href="#授權條款">授權條款</a>
|
||
</p>
|
||
|
||
<p align="center">
|
||
Claude-Mem 透過自動擷取工具使用觀察、產生語意摘要並在未來的工作階段中提供使用，無縫保留跨工作階段的脈絡。這使 Claude 即使在工作階段結束或重新連線後，仍能維持對專案的知識連續性。
|
||
</p>
|
||
|
||
---
|
||
|
||
## 快速開始
|
||
|
||
在終端機中開啟新的 Claude Code 工作階段，並輸入以下指令：
|
||
|
||
```
|
||
> /plugin marketplace add thedotmack/claude-mem
|
||
|
||
> /plugin install claude-mem
|
||
```
|
||
|
||
重新啟動 Claude Code。先前工作階段的脈絡將自動出現在新的工作階段中。
|
||
|
||
**主要功能：**
|
||
|
||
- 🧠 **持久記憶** - 脈絡跨工作階段保留
|
||
- 📊 **漸進式揭露** - 具有 Token 成本可見性的分層記憶擷取
|
||
- 🔍 **技能式搜尋** - 使用 mem-search 技能查詢專案歷史
|
||
- 🖥️ **網頁檢視介面** - 在 http://localhost:37777 即時檢視記憶串流
|
||
- 💻 **Claude Desktop 技能** - 從 Claude Desktop 對話中搜尋記憶
|
||
- 🔒 **隱私控制** - 使用 `<private>` 標籤排除敏感內容的儲存
|
||
- ⚙️ **脈絡設定** - 精細控制注入哪些脈絡
|
||
- 🤖 **自動運作** - 無需手動介入
|
||
- 🔗 **引用** - 使用 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)。
|
||
|
||
---
|
||
|
||
## License
|
||
|
||
This project is licensed under the **Apache License 2.0** (Apache-2.0).
|
||
|
||
Copyright (C) 2025 Alex Newman (@thedotmack). All rights reserved.
|
||
|
||
See the [LICENSE](LICENSE) file for full details.
|
||
|
||
Apache-2.0 allows broad use, modification, distribution, and commercial use, subject to its terms.
|
||
|
||
**Ragtime note**: The ragtime/ directory is licensed under the **Apache License 2.0**. See [ragtime/LICENSE](ragtime/LICENSE) for details.
|
||
|
||
---
|
||
|
||
|
||
## 支援
|
||
|
||
- **文件**：[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 開發**
|