个人学习小站 SIGNAL DESK 2026
LIVE --:--:-- 反馈
资讯 人工智能 OceanBase PowerContext GitHub README、官方文档与 benchmarks 页(2026-11-20 直核)+开源中国报道

Claude Code 开新会话就失忆:PowerContext 本地记忆部署避坑实录

OceanBase 开源的 PowerContext 把 Agent 决策、约束、进度存进对话外,Claude Code 与 Codex 共用一份。本文按实测顺序排坑:Hooks 不信任链路不跑、Basic/Full 模式凭证差异、Scope 不隔离串库,附八条急救清单。

2026年11月20日 12 小时前 作者 站长 约 6 分钟 12 阅读

全网讲 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 会串库。下面按实际安装顺序排坑。

PowerContext 双链路接入架构:Hook 自动召回与采集、MCP 显式存取、本地 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 两种记忆模式:不配凭证不是坏了

最容易翻车的认知差:装完以为「自动记住一切」,两天后判定白装。其实记忆分两档,能力差一倍:

Basic memory 模式与 Full memory 模式能力对比:是否需要模型 API 凭证

模式能做什么需要模型 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_foundDashboard 查该 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 串库还是凭证配置?评论区报一下工具组合和卡点,我按装机顺序帮你排。

登录后可点赞、收藏与反馈。

继续阅读 NEXT

更多 →