pi-agents-memory

Pi 的统一记忆插件入口，同时支持两个后端：

• viking-memory：火山引擎 Viking Memory API
• openviking：本地或远程 OpenViking REST API

安装一次：

pi install ./extensions/pi-agents-memory

通过环境变量选择唯一主动后端：

export PI_MEMORY_BACKEND=viking-memory
# 或
export PI_MEMORY_BACKEND=openviking

两个后端不会同时自动召回或写入。

抽取策略：会话内纯关键词，LLM 只在夜间

• 正常对话：turn_end 只跑关键词/规则分类（记住/以后/决定/改用/根因/已完成/package.json…）+ 噪声过滤 + 冲突门，不调模型，所以不会出现会话等待，也不吃会话 token。
• 每晚 00:00：独立进程读 ~/.pi/agent/sessions 里的会话记录，批量交给 LLM 抽取，走同一套写入与生命周期门。

# 先看 plist，再安装定时任务（请在已导出 MEMORY_API_KEY 的终端里执行）
node scripts/install-nightly.mjs --dry-run
node scripts/install-nightly.mjs

手动跑一次：/memory-nightly（openviking 后端：/memory-nightly）。开关与细节见 夜间记忆摸查。

文档

• 记忆架构调研
• 企业多用户检索
• 生命周期与可观测性
• 夜间记忆摸查（抽取策略）
• 企业 Memory 产品策略
• 本地 Docker OpenViking
• 抽取模板
• 机器可读策略
• 统一 Provider 契约
• Memory Platform 产品策略

本地基础能力

当前插件已包含本地可用的基础控制层：

• core/contracts.ts：MemoryIdentity、MemoryRecord、RequestContext、ConfigV1
• core/config-protocol.ts：版本化 canonical config 与本地 fallback
• core/content-scanner.ts：secret/threat candidate gate
• core/candidate-extractor.ts：纠正、故障、偏好、项目候选分类
• core/policy-engine.ts：chat/coding priority、quota、status/confidence/expiry 过滤
• core/lifecycle.ts：candidate/confirmed/superseded/conflicted/expired 状态和合并决策
• core/observability.ts：脱敏 stats、事件日志和 session audit

当前提供的 Pi 命令（两个后端共用同一套名字）：

/memory              状态与 search
/memory-stats        本地操作统计
/memory-audit        脱敏会话审计
/memory-capabilities 后端能力探测
/memory-workspace    当前 workspace 与全局桶
/memory-consolidate  扫描近似重复/矛盾记忆
/memory-nightly      立即跑一次离线会话摸查

旧的 /viking-memory*、/viking* 仍然可用（core/command-registry.ts 里的别名，描述会标注“旧命令名”）。

工具名同时从 viking_* / viking_memory_* 改为 memory_*（memory_search、memory_remember、memory_profile、memory_review，openviking 额外有 memory_read、memory_browse、memory_add_resource、memory_archive_expand）。

后台配置中心和外部鉴权尚未绑定；后续接入 MemoryIdentityResolver 和版本化配置 API，不需要重写 provider。

项目与全局记忆分层

不需要为每个项目维护 tenant/project/department 等一堆 ID。插件自动生成一个稳定 workspace ID：

1. PI_MEMORY_WORKSPACE_ID / MEMORY_WORKSPACE_ID：仅在你需要强制指定时设置；
2. 否则从 Git origin remote 生成：同一仓库在不同电脑、不同 clone 路径上仍是同一个 workspace；
3. 无 Git remote 时使用 cwd 指纹：安全地只限本机目录，不会和别的本地项目串。

召回是严格两层：当前 workspace 的项目记忆 + 用户全局 profile，不会召回其它项目的 event/project/decision。全局 profile 适合“回答尽量简明”“优先中文、先结论”等跨项目偏好；当前 workspace 适合语言/包管理器/代码风格/架构/测试命令等项目事实。

通常只需要：

export PI_MEMORY_BACKEND=viking-memory
export MEMORY_API_KEY='...'
# 可选：仅无 Git remote、monorepo 或你想人为统一多个目录时设置
export PI_MEMORY_WORKSPACE_ID='acme-platform'

后端配置

Viking Memory 使用 MEMORY_API_KEY、VIKING_MEMORY_COLLECTION、VIKING_MEMORY_PROJECT、VIKING_MEMORY_USER_ID、VIKING_MEMORY_ASSISTANT_ID。VIKING_MEMORY_GROUP_ID 仍兼容旧配置，但推荐使用更明确的 PI_MEMORY_WORKSPACE_ID。

OpenViking 使用 OPENVIKING_URL、OPENVIKING_API_KEY 或本地安全 ovcli.conf，本地 Docker 启动方式见 Docker 文档。

TUI 记忆卡片（可选，默认开启）

内存工具（memory_search/remember/profile，以及 OpenViking 的 memory_search/remember）在 Pi TUI 里默认以可展开的记忆卡片显示：一行折叠摘要 + 状态着色（进行中/成功/错误/空）+ 展开查看完整结果。渲染器实现见 core/tui/output-view.ts，零第三方依赖，与 pi-hermes-memory 的 shared output view 同属 pi-tui 组件模式。

它是工具的一个可选 renderResult 钩子；不想要时回到纯文本只需不传该字段（或注释 tools.ts 里的 renderResult: createMemoryCardRenderer()）。

pnpm test
# 或在仓库根目录执行全部测试
pnpm --dir ../.. test

远端测试数据和本地 runtime 配置不由插件自动删除；测试 marker 和清理边界见 verification/。