Claude Code 开新会话就失忆:PowerContext 本地记忆部署避坑实录
OceanBase 开源的 PowerContext 把 Agent 决策、约束、进度存进对话外,Claude Code 与 Codex 共用一份。本文按实测顺序排坑:Hooks 不信任链路不跑、Basic/Full 模式凭证差异、Scope 不隔离串库,附八条急救清单。
全网讲 AI 编码记忆的教程,九成停在「把项目背景写进 CLAUDE.md / AGENTS.md」。静态文件解决知识,解决不了进度:昨天在 Claude Code 里把重试方案改到第 3 版、41 项检查通过、签名校验还卡着——今天开新会话,或者切到 Codex,这些状态一概不在,要么重新口头交代,要么把几十轮对话全量重放一遍烧 token。
2026-11-20 实测的这条路线是 OceanBase 团队开源的 PowerContext:Apache-2.0 协议、GitHub 1755 Star、当前版本 v1.5.2,定位是本地起的上下文服务,把决策、约束、证据、进度存在对话外面,Claude Code、Codex、OpenCode 等十余个客户端共用同一份。官方基准:长对话记忆 LoCoMo 准确率 90.78%(同题全量上下文重放只有 52.9%),SWE-bench Pro 编码任务输入 token 少约 25.4%(约 2.25 亿 vs 3.02 亿 / 100 任务)。
结论先行:装得上(一行安装脚本)、跑得通(SQLite 加免模型 API 的 Basic 模式即可起步),但有两个几乎必踩的隐藏关卡——Hooks 不点信任,整条自动记忆链路不跑;Scope 不显式绑定,多项目共用一个 Server 会串库。下面按实际安装顺序排坑。

为什么 CLAUDE.md 写得再细,换会话照样失忆?
CLAUDE.md 是静态知识库:写进去的规则每次会话都加载,但它不会自己长出新内容。昨天会话里「重试用指数退避、最多 5 次、失败进死信队列」这个决策,你不手动写回去,下个会话就不知道。《换个 Agent 就得从头交代项目?AGENTS.md 三层知识库》那篇讲过:它管「项目是什么」,不管「干到哪了」。
| 方案 | 记什么 | 跨工具共用 | 维护成本 |
|---|---|---|---|
| CLAUDE.md / AGENTS.md | 手写规则与约定 | 各工具各一份,人工同步 | 人肉更新 |
| 对话摘要 / 全量重放 | 全部历史 | 部分支持 | 每次重放烧 token |
| PowerContext | 决策、约束、证据、进度,版本化条目 | Server 侧一份,多客户端共用 | Agent 产出+人工审批 |
核心差异在存储粒度:PowerContext 存的是带版本号的最小记忆条目(形如 atomic-memory/m_k2f9@3),不是对话截断。被批准的替换生成新 revision,读旧引用仍返回历史快照;标记 forgotten 不删历史、可恢复。记错想回滚、手滑想找回,都有版本兜底。
Basic 和 Full 两种记忆模式:不配凭证不是坏了
最容易翻车的认知差:装完以为「自动记住一切」,两天后判定白装。其实记忆分两档,能力差一倍:

| 模式 | 能做什么 | 需要模型 API |
|---|---|---|
| Basic memory | 显式保存+全文检索;Hook 自动采集 prompt 证据照常可用 | 不需要 |
| Full memory | 后台调度(默认 60 秒间隔)自动抽 Memory 与主题摘要+语义检索 | Generation + Embedding 两套凭证 |
关键一句:Claude Pro、Codex 套餐这类 Agent 订阅不提供 Server 用的凭证,Full 模式要单独配。没配也先别慌——Basic 模式显式让它存、显式让它查,全链路照样能验证;只有语义检索才依赖 Embedding。
四步装起来:一行脚本到 Claude Code 接上
macOS / Linux 官方推荐一行安装脚本,缺 Python 和 uv 会自动补:
curl -fsSL https://powercontext.oceanbase.io/install.sh | bash
# 配置向导:选存储、访问场景、记忆能力、Dashboard、要接的 Agent
powercontext config init
# 从 .env 所在目录启动,这个终端保持开着
powercontext server run --env-file .env
存储首推 SQLite,最省事;多人共用或 Kubernetes 部署再换 OceanBase 后端。Windows 支持标注 experimental:从源码装(社区博客实测 PowerShell 可跑通),要求 Git、uv、Python 3.11+:
git clone https://github.com/oceanbase/powercontext.git
cd powercontext
uv tool install --force ".[cli,server]"
powercontext config init --language zh --output ".powercontext/server.env"
接 Claude Code(社区插件,user 作用域安装):
powercontext setup claude-code --server-url http://127.0.0.1:8000
powercontext doctor claude-code
Codex 是官方集成:powercontext setup codex --ref powercontext-v1.5.2 之后跑 powercontext doctor codex。注意版本对齐:Python 包与插件必须用同一个 ref——旧 Server 配新插件时 recall 会被禁用,不报错、不阻塞,只是记忆注入悄悄停了,这是最隐蔽的一种翻车。
关键一步:/hooks 不点信任,记忆链路整条不跑
Codex 官方文档写得直白:新会话首次发消息前要打开 /hooks 信任 PowerContext hooks,否则 UserPromptSubmit hook 不启用——此时 MCP 面板显示一切正常,自动捕获和召回一条都不会跑。Claude Code 同理:装完用 /hooks 确认 UserPromptSubmit 与 SessionStart 两个 hook 在,用 /mcp 确认 powercontext Server 在,两条链路必须都通:
- recall 链路:UserPromptSubmit 每轮最多调一次 /v1/context/prepare,把带版本的 PreparedContext 注入上下文,默认预算 4096 字节;
- capture 链路:同一个 hook 独立地把 prompt 存为 Source 证据,与 recall 互不替代、各自失败;
- 显式通道:MCP 负责搜索、保存、修订、废弃记忆条目和 Handoff 交接。
整个设计是 fail-open:hook 出任何问题都不注入、也不报错不阻塞——401 记 authentication_failed,Server 不在记 server_unavailable,版本不齐记 version_mismatch。翻车时 Claude Code 照常干活,你只会隐约觉得「它怎么又失忆了」。所以装完必须做官方 Quick Start 里的 Source and Topic check:存一条决策,开新会话,看它能不能带引用召回。
Scope 不隔离的坑:会话标题和目录名都不是 ID
「claude-code-xxxxxxxx」这种会话标题不是 ID;Agent 名字和工作目录也不会自动隔离数据。同一台 Server 跑两个项目、都落在默认 Scope,A 项目的重试策略会混进 B 项目的上下文,轻则冗余,重则把编码方向带偏。
隔离只有显式一条路,解析顺序为:环境变量 POWERCONTEXT_CLAUDE_SCOPE_ID > 持久会话绑定 > 持久工作区绑定(workspace_scope.py --bind-scope)> Server 默认 Scope。另外 README 特别声明:Scope ID 只用于选择数据,不证明用户身份、不授予工具权限——多人共用的 Server 必须开 enforced 认证模式配 token,隐私别指望 Scope 本身。
常见翻车报错与急救清单
| 症状 | 根因 | 解法 |
|---|---|---|
| MCP 显示已连接,新会话却从不注入记忆 | hooks 未信任,或插件与包版本不齐(recall 禁用不报错) | /hooks 里点信任;插件与 Python 包对齐同一 ref 重跑 setup |
| /hooks 列表里没有 PowerContext 条目 | setup 没有成功执行 | 重跑 setup claude-code,核对输出里的安装版本与缓存路径 |
| hook 正常但注入内容为空 | PreparedContext 为 empty,或 scope_not_found | Dashboard 查该 Scope 下有无活跃条目;核对 Scope 绑定 |
| 提示 authentication_failed(401) | enforced 认证但插件没有凭据 | 带 POWERCONTEXT_CLAUDE_AUTHORIZATION 重跑 setup;token 别写进 URL |
| 连接被拒、明文 HTTP 报错 | 非回环地址默认拒绝明文 | 改 HTTPS 或回环地址;确需明文设 ALLOW_INSECURE_HTTP |
| 改了环境变量行为没变 | 桌面启动不继承终端变量 | 完全重启实际使用的 Claude 进程再测 |
| 记忆从不自动生成 | Full 模式未配 Generation/Embedding 凭证 | 配两套凭证,或先用 Basic 显式存取 |
| Windows 装不上、服务起不来 | Windows 支持为 experimental | 源码 uv tool install,确认 Python 3.11+ 与 uv;不行退回 WSL |
什么人该装,什么人直接劝退
适合:同时用两个以上编码工具、任务经常跨天接续、团队想把审查过的经验沉淀成共享 Skill(Experience 走人工审批后才进入召回)。注意它管的是「跨会话、跨工具的工作交接」,进程崩溃后的断线续跑是另一个问题域,参考《AgentScope Durable 断线续跑》。
劝退:单工具轻量用户,CLAUDE.md 加会话摘要已经够用;指望「全自动无痛记忆」的,Full 模式要自己供凭证、自动抽取还受 60 秒调度间隔约束;对常驻进程敏感的笔记本用户,Server 是本地常驻服务,还有后台调度在跑。
诚实边界:LoCoMo 90.78% 与 52.9% 的对比可按官方公开 harness 复现,可信;LoCoMo Plus 检索分数是项目方自报、运行产物未公开,参考即可。25.4% 的 token 节省是 SWE-bench Pro 官方口径,落到你的具体任务不一定同幅度。Windows 侧 experimental,生产主力机先观望。
最后留个互动:你的 Claude Code 每次开新会话要口头交代几句?是卡在 hooks 信任、Scope 串库还是凭证配置?评论区报一下工具组合和卡点,我按装机顺序帮你排。
登录后可点赞、收藏与反馈。