企业官网建设流程全解析

如何让 Agent 拥有跨会话长期记忆：PenguinHarness 记忆与 Vault 密钥管理详解

【免费下载链接】penguin-harness🐧 Unified and Stable RSI Platform项目地址: https://gitcode.com/gh_mirrors/pe/penguin-harness

PenguinHarness 是一款开源的本地优先多智能体应用开发平台，它内置了Agent 跨会话长期记忆（Memory）和Vault 密钥管理两大能力：Agent 会把用户偏好、项目决策整理成 Markdown 笔记，在每次新会话中自动召回；而 API Key 等敏感凭据则统一存放在密钥保险柜（Vault）里，只注入命令的环境变量，模型永远看不到密钥的值。本文用一次读的时间讲清这两块机制的设计与使用方法。

为什么 Agent 需要跨会话记忆 🧠

大多数 Agent 工具都有一个共同毛病：关掉会话就失忆。

• 你上周告诉它"我们项目统一用 pnpm"，这周它又开始建议你 npm；
• 同一个项目里换几个会话，之前的架构决策要反复解释一遍；
• 上下文压缩（Compaction）只能救活当前会话的短期状态，救不了长期知识。

PenguinHarness 的做法是：让 Agent 自己维护一套长期存储——位于agent_state/memory/下的 Markdown 笔记。它保存的正是那些"后续会话无法从代码库重新推导"的东西：用户是谁、长期偏好、项目决策及理由、指向外部系统的入口。

记忆不是上下文压缩。压缩保留的是单个 Session 的短期工作状态；Memory 是 Session 结束之后仍然幸存的东西。

设计细节可参考该功能的完整说明：changelog/0.2.2/2026-08-07-memory.zh.md。

记忆是如何工作的：两个作用域 + 一份索引

PenguinHarness 的记忆分两个作用域，都只属于同一个 Agent，绝不与其他 Agent 共享：

目录结构长这样：

agent_state/memory/ ├── user/ # 用户作用域（随 Agent 一同创建） │ ├── MEMORY.md # 该作用域的索引 │ └── prefers-pnpm.md └── my-app-a81f32c4/ # 某个 Workspace 的记忆 ├── MEMORY.md └── testing-conventions.md

几个值得注意的设计：

• 每个作用域有自己的MEMORY.md索引，每条记忆一行：- 标题 — 钩子；
• 每条记忆是一个主题文件（frontmatter 含name/description/updated_at），而不是按任务或日期散落的碎片；
• 绝不会被保存的内容：凭证、任务进度、未经确认的猜测，以及代码和 Git 历史本身就说明了的事实。

什么会真正进入模型：只有索引

为了控制 token 开销，每次会话注入上下文的是MEMORY.md索引（经系统提示词的{{MEMORY}}占位符展开），而不是全部正文。注入上限为每作用域 200 行、合计 25,000 字符；超出时模型会被提示自行打开完整的MEMORY.md。正文则按需读取——读取、写入和去重都由 Agent 用普通文件工具自己完成。

在 Web App 中管理记忆：查看、编辑、导入导出

打开某个 Agent 的设置页，在记忆（Memory）标签页可以集中管理全部记忆：按作用域分组展示（用户记忆在前，之后每个 Workspace 一组），每条记忆一行，支持：

• 查看：侧边面板显示标题、日期、描述与完整正文；
• 编辑：打开新对话，由 Agent 更新记忆文件与索引（记忆内容刻意不开放就地编辑，保证索引与正文一致）；
• 删除：确认后删除文件，并机械地移除MEMORY.md中对应行；
• 添加 / 导入 / 导出：粘贴文本、文件路径或 URL 交给 Agent 整理成记忆；分组可整组导出为 JSON，再按需导入（含"保留现有 / 改用文件版本 / 整组替换"三种冲突策略）。

顶部的启用记忆开关切换后立即生效：关闭只是让记忆不再进入上下文，不会删除任何文件。相关操作说明见 Agent 设置文档。

Vault 密钥管理：模型只看得见变量名，看不见值 🔐

Agent 干活经常需要 API Key。把密钥贴在对话里或写进提示词，等于发给模型供应商并永久留在 Trace 里。PenguinHarness 的答案是密钥保险柜（Vault）：

• 变量按 Agent 保存在agent_state/.vault.toml（0600 权限的隐藏文件）；
• 值只注入 Agent 命令的子进程环境变量，从不进入模型上下文——模型只能看到变量名（{{VAULT_KEYS}}列出的名单），永远看不到值；
• 子 Agent 使用各自的 Vault，不继承父 Agent 的变量；
• 修改从下一个 Task 生效，正在运行的 Task 不受影响；
• 权限上，只有 Project owner 能修改 Vault，成员看到的值全部是掩码。

两种添加变量的方式

手动添加（推荐）：在密钥保险柜标签页选手动创建，输入键名（如OPENAI_API_KEY）和值即可。

用 AI 创建：描述需要的变量（例如"盘点这个智能体需要的 key"），Project 的默认 Agent 会用penguin config vault set写入。也可以直接用 CLI 管理：

penguin config vault set --key GITHUB_TOKEN --value ghp_xxx penguin config vault list penguin config vault remove --key GITHUB_TOKEN

⚠️ 安全提示：在 AI 对话框里直接输入的密钥值会发送给模型供应商并记录进 Trace。更安全的做法是让 AI 只创建变量名、说明用途，然后自己在保险柜标签页填入值。

CLI 用法详见 CLI 文档。

数据落在哪里：全部是可编辑的本地文件

PenguinHarness 是"本地优先"的——Agent 的全部行为都是可编辑的文件，记忆与密钥也不例外：

记忆随 Agent State 一起迁移：导出、导入和快照都会带上（但快照刻意排除 Vault，密钥永远不会随快照流走）。完整的存储分层见 架构文档 与 配置参考。

常见问题

记忆会泄露给其他 Agent 吗？不会。每个 Agent 的记忆只属于它自己，即使多个 Agent 在同一个 Workspace 工作也互不可见。

关闭记忆开关会删数据吗？不会。关闭只是阻止记忆进入上下文、不再为新会话准备目录，文件原样保留。

移动项目目录后记忆还在吗？旧记忆仍以旧键留在磁盘上（Workspace 键基于真实路径哈希），新路径被视为新 Workspace。

小结

PenguinHarness 给 Agent 装上"长期记忆"的思路很克制：

1. 记忆 = Markdown 文件：两个作用域、一份索引、按需读取，透明可编辑；
2. 密钥 = Vault 环境变量：值只进命令子进程，模型只见名不见值；
3. 一切本地优先：数据都在agent_state/下，可导出、可迁移、可随时关掉。

想动手试试的话，从 Agent 设置文档 的"记忆标签页"和"密钥保险柜标签页"两节开始，十分钟就能跑起来。

【免费下载链接】penguin-harness🐧 Unified and Stable RSI Platform项目地址: https://gitcode.com/gh_mirrors/pe/penguin-harness