如何让 Agent 拥有跨会话长期记忆PenguinHarness 记忆与 Vault 密钥管理详解【免费下载链接】penguin-harness Unified and Stable RSI Platform项目地址: https://gitcode.com/gh_mirrors/pe/penguin-harnessPenguinHarness 是一款开源的本地优先多智能体应用开发平台它内置了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 共享作用域目录存什么谁读取用户记忆memory/user/用户是谁、长期偏好、不绑定代码库的参考资料每个会话Workspace 记忆memory/workspace-key/某个项目里的决策、约定、外部系统入口同 Agent 在同 Workspace 的会话目录结构长这样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.toml0600 权限的隐藏文件值只注入 Agent 命令的子进程环境变量从不进入模型上下文——模型只能看到变量名{{VAULT_KEYS}}列出的名单永远看不到值子 Agent 使用各自的 Vault不继承父 Agent 的变量修改从下一个 Task 生效正在运行的 Task 不受影响权限上只有 Project owner 能修改 Vault成员看到的值全部是掩码。两种添加变量的方式手动添加推荐在密钥保险柜标签页选手动创建输入键名如OPENAI_API_KEY和值即可。用 AI 创建描述需要的变量例如盘点这个智能体需要的 keyProject 的默认 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/memory/按作用域分目录各带MEMORY.md索引密钥保险柜agent_state/.vault.toml0600 权限值只进子进程环境记忆/保险柜提示词agent_state/system_config.yamlmemory.prompt、vault.prompt均可在对应标签页编辑记忆随 Agent State 一起迁移导出、导入和快照都会带上但快照刻意排除 Vault密钥永远不会随快照流走。完整的存储分层见 架构文档 与 配置参考。常见问题记忆会泄露给其他 Agent 吗不会。每个 Agent 的记忆只属于它自己即使多个 Agent 在同一个 Workspace 工作也互不可见。关闭记忆开关会删数据吗不会。关闭只是阻止记忆进入上下文、不再为新会话准备目录文件原样保留。移动项目目录后记忆还在吗旧记忆仍以旧键留在磁盘上Workspace 键基于真实路径哈希新路径被视为新 Workspace。小结PenguinHarness 给 Agent 装上长期记忆的思路很克制记忆 Markdown 文件两个作用域、一份索引、按需读取透明可编辑密钥 Vault 环境变量值只进命令子进程模型只见名不见值一切本地优先数据都在agent_state/下可导出、可迁移、可随时关掉。想动手试试的话从 Agent 设置文档 的记忆标签页和密钥保险柜标签页两节开始十分钟就能跑起来。【免费下载链接】penguin-harness Unified and Stable RSI Platform项目地址: https://gitcode.com/gh_mirrors/pe/penguin-harness创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考