claude-code-live-memory

██╗ ██╗██╗ ██╗███████╗ ██║ ██║██║ ██║██╔════╝ ██║ ██║██║ ██║█████╗ ██║ ██║╚██╗ ██╔╝██╔══╝ ███████╗██║ ╚████╔╝ ███████╗ ╚══════╝╚═╝ ╚═══╝ ╚══════╝ ███╗ ███╗███████╗███╗ ███╗ ██████╗ ██████╗ ██╗ ██╗ ████╗ ████║██╔════╝████╗ ████║██╔═══██╗██╔══██╗╚██╗ ██╔╝ ██╔████╔██║█████╗ ██╔████╔██║██║ ██║██████╔╝ ╚████╔╝ ██║╚██╔╝██║██╔══╝ ██║╚██╔╝██║██║ ██║██╔══██╗ ╚██╔╝ ██║ ╚═╝ ██║███████╗██║ ╚═╝ ██║╚██████╔╝██║ ██║ ██║ ╚═╝ ╚═╝╚══════╝╚═╝ ╚═╝ ╚═════╝ ╚═╝ ╚═╝ ╚═╝ 总是保持最新的代码库内存，适用于克劳德代码 · 提问，而不是重新阅读 # 实时内存 — 克劳德代码插件 **一种廉价、始终在线的模型，能够学习您的代码库 — 让您的代理停止重新阅读它。** 实时内存运行一个单独的、廉价的大型上下文模型，作为一个长期运行的MCP服务器，积累 跨会话的代码库知识。 与其在每个会话中重新读取相同的文件，您的 代理询问一个只读工具，`ask_live_memory`，广泛理解问题 — *"在哪里X，如何工作Y，什么调用Z"* — 实时内存以一种方式回答，**引导主要代理开始进行生产性工作** （例如，编辑）。 它 **被动学习** 来自代理自己的读取和编辑 （通过钩子传递 - 无需额外读取）并随着代码库更改保持最新（修改和删除）。 只读且路径隔离（它永远不能编辑，创建或运行任何东西）; 在克劳德订阅上零配置（俳句，无API密钥）; 内存模型是可插拔的 - 将其指向本地模型或任何 OpenAI兼容端点。  ## 工作原理 ```mermaid flowchart LR repo[("您的代码库")] subgraph sessions["克劳德代码会话 — 高级模型（多个，随时间）"] agent["代理"] end agent -->|"读取/编辑文件"| repo agent -. "PostToolUse / FileChanged钩子<br/>tee文件内容 — 被动学习（免费）" .-> lm agent ==>|"ask_live_memory（问题，cwd）<br/>只读MCP工具"| lm lm ==>|"有根据的答案 — 无需重新读取文件"| agent subgraph server["实时内存 — 每个工作区一个MCP服务器（单例）"] lm["廉价/本地大型上下文模型<br/>+ 累积上下文窗口<br/>追加式 · 中性压缩到账本"] lm --> snap[("本地JSON快照<br/>跨会话持久化")] end ``` 您的代理 **像往常一样读取或编辑文件**; 钩子悄悄地将内容传递给服务器，以便它 **免费学习**。 当代理需要了解某些内容时，它会 **询问** `ask_live_memory` 而不是重新读取 — 服务器从其累积的、每个工作区的内存（或读取代码本身，只读，如果它尚未看到）中回答。 一个服务器为每个会话提供服务，并 **跨会话持续**。 ## 基准测试 在一个真实的代码库上进行A/B测试，**每个任务的成本，运行到完成**。 成本以三种方式显示：**高级（构建）模型的账单** — 您的 *昂贵* 模型花费的费用，因为伴侣运行在廉价或本地模型上 — 以及 **全部计入**，还包括伴侣在 **DeepSeek-v4-flash** 或 **Haiku** 上的自身成本： | 每个任务 | 高级模型账单 | 全部计入 · DeepSeek-flash† | 全部计入 · Haiku | 更快 | | --- | --- | --- | --- | --- | | **理解密集型** （跟踪/理解） | **-61%** | **-57%** | **-25%** | **〜22%** | | **混合型** （理解后编辑：错误修复+功能） | **-28%** | **-26%** | **-11%** | **〜11%** | | 纯编辑/执行 | 〜收支平衡 | 〜收支平衡 | 〜收支平衡 | 〜0 | 理解密集型工作还卸载了 **〜93%** 的高级模型代码库读取令牌（具有较低的成本方差），并且正确性在混合任务中从未倒退（**12/12** 在启用和禁用后均通过）。 DeepSeek-v4-flash **匹配Haiku的答案准确率** （98％ vs 91％，在3次复制中） ，价格约为 **8倍** 的令牌价格; **本地** 伴侣 ≈ 免费，因此全部计入 ≈ 高级模型账单。 完全可复制 + 审计 （人为 + 寓言）。 完整的数字 + 方法论： [`benchmark/results/RESULTS.md`](./benchmark/results/RESULTS.md). _{† 伴侣重新定价为DeepSeek-v4-flash费率（〜便宜8倍于Haiku）; 准确的理解情况，源自混合情况的测量成本比率。} **血统：** 实时内存始于 **[shofer.dev](https://shofer.dev)** （Arkware的并行多代理编码平台）的功能，其中会话共享同步代码库内存。 这就是这个想法作为一个 **独立的克劳德代码插件** — 一个全新的实现，自我包含，无依赖于shoфер。 克劳德代码插件家族的一部分（与 [slang-workflows](https://github.com/shofer-dev/claude-code-slang-orchestrator) 一起). ## 快速入门 live-memory 是一个 **您只需运行一次的HTTP MCP服务器** （一个单例，为所有克劳德代码会话服务） 加上一个注册 `ask_live_memory`、钩子和斜杠命令的插件。 **首先启动服务器** — 克劳德代码仅 *连接* 到它（它从不启动它），因此如果它没有运行，您将收到 连接错误。 **1 — 启动服务器** （在克劳德订阅上零配置 → 俳句; 无需API密钥）： ```bash git clone https://github.com/shofer-dev/claude-code-live-memory cd claude-code-live-memory/deploy && ./install-service.sh # 虚拟环境 + 用户systemd服务，自动在启动时启动 # …或者直接在终端中运行： # cd claude-code-live-memory/server && pip install -e . && python -m live_memory ``` **2 — 安装插件** （在克劳德代码会话内）： ``` /plugin marketplace add shofer-dev/claude-code-live-memory /plugin install live-memory@shofer-live-memory ``` 询问您的代理一个整个代码库的问题 — 它将调用 `ask_live_memory` 而不是读取文件。 `/live-memory-stats` 显示累积知识 + 成本 · `/live-memory-config` 切换 模型/提供者 · `/live-memory-empty` 清除内存。 提供者、systemd、工作区和并发性 在下面有详细介绍。 ## 形状 ``` live-memory/ ├── .claude-plugin/plugin.json # 插件清单 ├── .mcp.json # 注册服务器（类型：http，显式超时） ├── hooks/ # PostToolUse（Read | Write | Edit | ...）+ FileChanged → TEE文件内容（被动学习） │ ├── hooks.json │ └── notify.py ├── skills/live-memory/SKILL.md # 告诉代理何时/为什么调用ask_live_memory ├── commands/ # 面向用户的斜杠命令（不是代理工具） │ ├── live-memory-stats.md # /live-memory-stats → GET /stats │ ├── live-memory-config.md # /live-memory-config → 设置模型/提供者，热重载 │ ├── live-memory-empty.md # /live-memory-empty → 清除内存（此工作区或`all`） │ ├── stats.py · config.py · empty.py ├── settings.json ├── deploy/ # systemd单元 + 环境示例 + install-service.sh └── server/ # 长期运行的MCP服务器（Python，asyncio） ├── pyproject.toml # 依赖项 + mypy（严格）+ pytest配置 ├── tests/ # pytest单元测试套件（模拟; 无网络） └── live_memory/ ├── __main__.py # 入口点：python -m live_memory ├── server.py # MCP（HTTP）ask_live_memory + /health + /stats + /notify + /reload ├── workspace.py # 每个工作区状态注册表（窗口 + 队列 + 存储）; 分叉/提交 ├── manager.py # 代理循环（处理一个问题）; 压缩 ├── context_window.py # 预算; 文件上下文驱逐，Q&A总结; 分叉/克隆 ├── summarizer.py # 中性，查询无关的知识账本总结 ├── question_queue.py # 每个工作区的准入（串行/并行）+ 每个条目的超时 ├── async_jobs.py # 可选的fire-and-forget作业注册表（提交/轮询） ├── keep_warm.py # 后台KV/提示缓存保持温暖循环 ├── conversation_store.py # 版本化JSON快照（SHA-256文件验证） ├── llm_client.py # 提供者可插拔：Anthropic Messages | OpenAI兼容 ├── oauth.py # 订阅OAuth凭证 + 自动刷新（零配置） ├── config.py # 分层配置（env > config.json > 默认值）+ 提供者知识 ├── constants.py # 所有可调谐的魔法数字 + 默认值，集中（配置从此处获取默认值） ├── models.py # 核心数据类（ChatMessage，FileContext，QuestionResult，...） ├── tool_executor.py # 只读工具（Read/Grep/Glob/find_paths/git/...），路径隔离 ├── directory_tree.py # 工作区扫描，〜10％上下文上限 ├── pricing.py # 每个模型USD成本（+ 环境覆盖） ├── logging_setup.py # stderr→journald + 可选的旋转文件 └── prompts.py # 系统提示 + 中性总结提示 ``` ## 架构（参见DESIGN.md获取完整原理） - **一个外部监督的，幂等的HTTP MCP服务器** （单例）为所有 克劳德代码会话服务; 状态按 **工作区** （`cwd`）键入。 - **模型 = 独立 + 提供者可插拔** ：服务器运行其 *自己的* 廉价 模型（不是会话的）。 两个适配器涵盖了几乎所有情况 — **Anthropic Messages** （带有`cache_control`）和 **OpenAI兼容** （DeepSeek/OpenAI/网关）。 **零配置** ：无需密钥，只需克劳德订阅，它使用订阅 OAuth令牌（自动刷新）在 **俳句** 上。 - **被动（有机）学习** ：PostToolUse/FileChanged钩子 **tee文件内容** 进入内存，因此它从实际工作中免费预热; `ask_live_memory` 是未见内容的主动备用。 - **追加窗口，压缩之间**; 压缩 = **批量中性总结** ，带有高/低水位标记（罕见，批量） — 观察到的文件 + 问答 提炼成查询无关的知识账本 — 永远不会进行前向截断。 - **两层超时** ：`ask_live_memory（问题，cwd，超时）` — 软 `超时` 通知模型的预算并产生最佳努力答案，然后是硬`.mcp.json` MCP超时。 - **人类状态** 通过 `/live-memory-stats` 斜杠命令（→ `/stats`），使其远离代理的工具表面。 ## 安装 **先决条件：** Python ≥ 3.10; **ripgrep** （`rg`）推荐（支持 `Grep`）; `git` 可选（支持 `git_search` / `get_changed_files`）。 **1. 安装服务器：** ```bash cd server pip install -e . # 运行时依赖项（mcp，anthropic，starlette，uvicorn，watchdog，httpx） # 用于开发/测试： pip install -e ".[dev]" # 添加mypy，pytest，pytest-asyncio ``` **2. 将插件安装到克劳德代码** 中，使其读取 `.mcp.json`、钩子、技能和斜杠命令。 仓库根目录兼作单个插件 **市场** （`.claude-plugin/marketplace.json`）; `/plugin install` 仅从 **市场** 安装，而不从裸目录安装 — 因此请先添加市场，然后从中安装。 在克劳德代码会话内： ``` /plugin marketplace add https://github.com/shofer-dev/claude-code-live-memory /plugin install live-memory@shofer-live-memory ``` `shofer` 是市场名称; `live-memory` 是插件名称。 要从本地克隆安装，请将 `add` 指向检出目录： ``` /plugin marketplace add /ABSOLUTE/PATH/TO/claude-code-live-memory /plugin install live-memory@shofer-live-memory ``` 编辑插件文件后，运行 `/plugin marketplace update shofer` 然后 `/reload-plugins` （已安装的插件缓存在 `~/.claude/plugins/` 下，因此 源代码编辑不会实时生效）。 **用于本地开发** ，跳过市场，直接启动克劳德代码 并加载插件： ```bash claude --plugin-dir /ABSOLUTE/PATH/TO/claude-code-live-memory ``` （步骤3中的服务器必须在克劳德代码连接之前运行 — `.mcp.json` 指向一个 `type:http` 端点，克劳德代码仅 *连接* 到，从不启动; 如果 服务器关闭，您将在 `/plugin` 的“错误”选项卡中看到连接错误。） **3. 运行服务器** （下一节）。 **4. 开发检查：** `mypy live_memory/ && pytest` 。 ## 运行服务器 HTTP传输需要服务器在克劳德代码连接之前 **已经运行** （克劳德代码不会启动 `type:http` 服务器） — 在外部监视器下运行（systemd/container/etc.）。 **零配置** （无需API密钥）：如果您登录到克劳德订阅，它 直接工作 — 服务器重用该凭证（自动刷新）在 **俳句** 上。 ```bash cd server && pip install -e . python -m live_memory # 在 http://127.0.0.1:7711/mcp 提供MCP服务（+ /health, /stats, /notify, /reload） ``` > 订阅路径利用您的订阅的 **速率限制预算** （不是 > 计费） — 文档中提到的一项服务协议灰色地带。对于始终在线的服务，更喜欢使用密钥。 **选择任意模型/提供者** — 环境变量 *或* `/live-memory-config` 斜杠命令（写入 `config.json` ，热重载，无需重启）： ```bash # DeepSeek（廉价，推荐），通过环境变量： LIVE_MEMORY_PROVIDER=openai LIVE_MEMORY_BASE_URL=https://api.deepseek.com \ LIVE_MEMORY_API_KEY=sk-... LIVE_MEMORY_MODEL=deepseek-chat python -m live_memory # …或在运行时，从克劳德代码内部： /live-memory-config set provider=openai base_url=https://api.deepseek.com model=deepseek-chat api_key=sk-... /live-memory-config show ``` 支持的提供者：`anthropic` （Messages API + Bedrock/Vertex/网关，API密钥 或订阅OAuth）和`openai` （任何OpenAI兼容端点：OpenAI， DeepSeek，本地模型，网关）。然后启用插件，以便克劳德代码读取 `.mcp.json` 并连接到它。 ## 作为systemd服务运行 `deploy/` 有样板。 一个命令注册并启动它： ```bash cd deploy ./install-service.sh # 用户服务（推荐 — 参见下文） ./install-service.sh --system # 系统范围（适用于API密钥设置最佳） ``` 它创建了一个虚拟环境 + 安装服务器，写入一个配置文件 `~/.config/live-memory/live-memory.env` （来自 `live-memory.env.example` — 编辑它 用于提供者/模型/密钥），安装 `live-memory.service` ，启用延迟启动并 启动它。 配置通过 systemd 作为环境文件提供给进程。 - **持久性在重启后自动生存** ：每个工作区的快照位于 `LIVE_MEMORY_DATA_DIR` （默认为 `~/.claude/plugins/data/live-memory`），因此重启后 每个工作区的内存将在其下一个查询中重新加载。 - **订阅（零配置）身份验证需要一个 *用户* 服务** （默认）：它 以您的身份运行，因此它可以读取 `~/.claude/.credentials.json` 并重用您的克劳德 登录凭证（自动刷新）。 `--system` 服务也可以执行此操作，但单元 必须设置 `User=` + `Environment=HOME=…` （安装程序为您执行此操作）。 ```bash systemctl --user status live-memory journalctl --user -u live-memory -f systemctl --user restart live-memory # 编辑env文件后 ``` ### 日志 默认情况下，服务器日志记录到 **stderr** ，systemd将其捕获到 **日志** — 带有旋转和单元/进程ID元数据的惯用位置： ```bash journalctl --user -u live-memory -f # 用户服务 sudo journalctl -u live-memory -f # 系统服务 ``` 两个注意事项和逃生舱： - **用户** 服务的日志仅在journald具有 持久存储时才在重启后持续存在（如果您的存储为volatile，则日志将在重启后消失）。 - 为了使日志为持久且可grep的纯文本日志，无论如何，请设置 `LIVE_MEMORY_LOG_FILE` （例如， `/var/log/live-memory/live-memory.log` ，适用于 系统服务，或用户服务的 `~/.local/state/live-memory/` 下的绝对路径）。它是一个 **旋转** 处理程序（ `LIVE_MEMORY_LOG_MAX_BYTES` × `LIVE_MEMORY_LOG_BACKUPS` ）并写入 **除了** journald。 `LIVE_MEMORY_LOG_LEVEL` （默认为 `INFO` ）调整详细程度。 ## 工作区和 `cwd` 内存按 `cwd` 键入，从传递给 `ask_live_memory` 的 `cwd` 。 `cwd` 必须是 **绝对** 路径（拒绝相对路径 — 共享服务器无法将其解析为您的会话）。 默认情况下，服务器将每个 `cwd` 快照到其包含的 **git仓库根目录** ，因此子目录和仓库根目录共享一个内存： | 环境变量 | 默认值 | 效果 | | --- | --- | --- | | `LIVE_MEMORY_CANONICALIZE_WORKSPACE` | `true` | 将 `cwd` 快照到其git仓库根目录。设置为 `false` ，为每个确切目录提供不同的内存。 | | `LIVE_MEMORY_REPO_ROOT_MODE` | `nearest` | 在子模块/工作树中：`nearest` = 子模块自己的根目录（git的默认值）; `outermost` = 超级项目根目录（将子模块问题折叠到父目录的内存中）。 | ### 并发 对 **相同** 工作区的查询由以下两种模式之一允许： | 环境变量 | 默认值 | 效果 | | --- | --- | --- | | `LIVE_MEMORY_CONCURRENCY` | `parallel` | `parallel` （默认）= 无队列延迟 — 每个问题都分叉窗口，最多 `MAX_PARALLEL_QUERIES` 个问题同时运行，每个问题探索最多的代码库提交回（其他问题仍返回答案但不更新共享内存）。 `serial` = 每个工作区一次问题（共享窗口就地增长; 缓存局部性最强，并发调用者等待）。 | | `LIVE_MEMORY_MAX_PARALLEL_QUERIES` | `4` | `parallel` 模式下每个工作区的最大并发问题数量。 | （对 **不同** 工作区的查询始终并发运行，无论此设置如何。） ### 异步（fire-and-forget）工具 — 可选 MCP工具调用会阻塞调用者的回合，直到它们返回。 如果您希望代理 提交一个慢速查询，继续工作，并在稍后收集答案，请设置 `LIVE_MEMORY_ASYNC_TOOLS=true` 以额外公开： - `ask_live_memory_submit（question, cwd, timeout）` → 返回一个 `job_id` 立即。 - `ask_live_memory_result（job_id）` → 准备好的答案，或 `[running]` 再次轮询。 代理驱动轮询（克劳德代码无法将完成推送到正在运行的 回合）。 默认情况下关闭; `ask_live_memory` （同步）始终可用。 ### 缓存预热 **默认关闭** — 可选设置 `LIVE_MEMORY_KEEP_WARM=true` 。后台循环 每隔一段时间就ping一个最近活跃的工作区的prefix（`max_tokens=1`，输出丢弃） ，以便提供者的KV/prompt缓存不会在问题之间变冷 — 使下一个真实查询 的缓存命中率定价，而不是完全冷读。间隔是提供者知识：〜240s 适用于Anthropic/OpenAI（分钟级缓存），并自动设置为 **DeepSeek** 的非常长的时间 （其磁盘缓存持续数小时/天，即使启用它也会自行禁用）。 通过 `LIVE_MEMORY_KEEP_WARM_INTERVAL_S` 重写，或通过 `LIVE_MEMORY_KEEP_WARM_MAX_IDLE_S` 更早地停止预热空闲工作区。 `/live-memory-stats` 显示缓存上次刷新时间。