airkjw/claude-mem
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Files
d17b372b60a1584ddda579f19276c4baea445596
claude-mem/docs/i18n/README.zh-tw.md
T
Alex Newman 36b0929fae Server-beta: Postgres storage + independent runtime + BullMQ queue (Phases 1–3) (#2351) 
* 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>
2026-05-08 01:20:07 -07:00

12 KiB
Raw Blame History

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


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。先前工作階段的脈絡將自動出現在新的工作階段中。

主要功能：

  • 🧠 持久記憶 - 脈絡跨工作階段保留
  • 📊 漸進式揭露 - 具有 Token 成本可見性的分層記憶擷取
  • 🔍 技能式搜尋 - 使用 mem-search 技能查詢專案歷史
  • 🖥️ 網頁檢視介面 - 在 http://localhost:37777 即時檢視記憶串流
  • 💻 Claude Desktop 技能 - 從 Claude Desktop 對話中搜尋記憶
  • 🔒 隱私控制 - 使用 <private> 標籤排除敏感內容的儲存
  • ⚙️ 脈絡設定 - 精細控制注入哪些脈絡
  • 🤖 自動運作 - 無需手動介入
  • 🔗 引用 - 使用 ID 參考過去的觀察（透過 http://localhost:37777/api/observation/{id} 存取，或在 http://localhost:37777 的網頁檢視器中檢視全部）
  • 🧪 Beta 通道 - 透過版本切換試用 Endless Mode 等實驗性功能

文件

📚 檢視完整文件 - 在 GitHub 上瀏覽 Markdown 文件

入門指南

最佳實務

架構

設定與開發

運作原理

核心元件：

  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 向量資料庫 - 用於智慧脈絡擷取的混合語意 + 關鍵字搜尋

詳情請參閱架構概覽。

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 永遠可見）

使用範例：

// 步驟 1：搜尋索引
search(query="authentication bug", type="bugfix", limit=10)

// 步驟 2：檢閱索引，識別相關 ID（例如 #123、#456）

// 步驟 3：擷取完整詳情
get_observations(ids=[123, 456])

詳細範例請參閱搜尋工具指南。

Beta 功能

Claude-Mem 提供具有實驗性功能的 Beta 通道，例如 Endless Mode（用於延長工作階段的仿生記憶架構）。在 http://localhost:37777 → Settings 的網頁檢視介面中切換穩定版與 Beta 版。

有關 Endless Mode 與如何試用的詳情，請參閱 Beta 功能文件。

系統需求

  • Node.js：18.0.0 或更高版本
  • Claude Code：具有外掛支援的最新版本
  • Bun：JavaScript 執行環境與程序管理員（如缺少將自動安裝）
  • uv：用於向量搜尋的 Python 套件管理員（如缺少將自動安裝）
  • SQLite 3：用於持久儲存（已內建）

設定

設定在 ~/.claude-mem/settings.json 中管理（首次執行時自動以預設值建立）。設定 AI 模型、Worker 連接埠、資料目錄、日誌層級與脈絡注入設定。

所有可用設定與範例請參閱 設定指南。

開發

建置說明、測試與貢獻工作流程請參閱 開發指南。

疑難排解

如遇問題，向 Claude 描述問題，troubleshoot 技能將自動診斷並提供修正。

常見問題與解決方案請參閱 疑難排解指南。

錯誤回報

使用自動產生器建立完整的錯誤回報：

cd ~/.claude/plugins/marketplaces/thedotmack
npm run bug-report

貢獻

歡迎貢獻！請依照以下步驟：

  1. Fork 儲存庫
  2. 建立功能分支
  3. 加入測試並進行變更
  4. 更新文件
  5. 提交 Pull Request

貢獻工作流程請參閱開發指南。

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 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 for details.

支援

使用 Claude Agent SDK 建置 | 由 Claude Code 驅動 | 以 TypeScript 開發

Reference in New Issue View Git Blame Copy Permalink