capsule-memory 原理揭秘before_build Hook 如何把记忆注入系统提示词【免费下载链接】capsule-memoryCross-session memory. Reads local memory state and injects it into the system prompt through hooks. Part of Unicity AOS.项目地址: https://gitcode.com/gh_mirrors/ca/capsule-memory如果你正在研究 AI Agent 的跨会话记忆cross-session memory方案capsule-memory 是一个极简而精彩的开源项目它只靠一个before_buildHook就能在每次构建提示词时把本地memory.md文件注入到系统提示词system prompt中让 Agent 在新会话里记住上次的上下文 。本文将用通俗的方式讲清它的完整工作原理。capsule-memory 是什么Agent 的持久化内存条capsule-memory 是 Astrid OSUnicity AOSAgent 系统的一个 Rust 编写的WASM 记忆胶囊在操作系统隐喻中被定位为持久化交换文件——负责把上下文跨越会话边界传递过去README.md#L6-L8。它有两个关键设计取向非常适合作为学习案例只做读/注入胶囊本身不写文件Agent 通过已有的文件系统工具write_file、replace_in_file自己写记忆无需新增工具README.md#L24-L26零新依赖核心逻辑全部在一个文件 src/lib.rs 中实现依赖仅 astrid-sdk、serde 等基础库核心原理before_build Hook 三步完成记忆注入整个注入流程发生在 Agent 每次组装提示词的瞬间源码入口是on_before_prompt_build拦截器src/lib.rs#L66-L115。它订阅了prompt_builder.v1.hook.before_build事件事件与响应的绑定关系声明在 Capsule.toml#L17-L21 中。1️⃣ 读取两级记忆文件capsule-memory 支持两个粒度的记忆源两者都是可选的缺失或为空会静默跳过src/lib.rs#L58-L64记忆类型路径内容定位注入策略个人记忆home://memory.md用户偏好、沟通风格、长期事实始终注入项目记忆cwd://{cwd_dir}/memory.md默认.astrid/memory.md项目上下文、当前进展、约定仅在工作于项目内时注入注入顺序固定个人记忆在前项目记忆追加在后src/lib.rs#L11-L17。项目文件夹名通过cwd_dir环境变量注入重品牌的发行版只需在 Distro.toml 里设置cwd_dir .myagent即可无需 forkCapsule.toml#L23-L26。2️⃣ 包装为 Memory 章节每段记忆被包装成独立的 Markdown 章节并拼接在一起# Memory (personal) 个人记忆内容 # Memory (project) 项目记忆内容格式化逻辑见 src/lib.rs#L88-L103。如果两个记忆源都不存在胶囊直接返回对提示词零侵入——这就是 README 所说的 no-op 行为。3️⃣ 发布 appendSystemContext 响应最后一步胶囊通过ipc::publish_json把{appendSystemContext: sections}发布到当前请求专属的响应主题response_topic上提示词构建器据此把记忆章节追加进系统提示词src/lib.rs#L105-L114。注意response_topic是按请求下发的这保证了记忆只注入到当前这次提示词构建不会串到其他请求。安全细节32KB 截断如何防止上下文爆炸Agent 自己写的记忆内容会无限增长不像人类撰写的AGENTS.md那样稳定因此 capsule-memory 设置了32KB 硬性上限src/lib.rs#L24-L28上限独立应用于个人记忆与项目记忆防止任何一方挤占另一方的空间截断时按UTF-8 字符边界处理避免截断出乱码floor_char_boundary实现见 src/lib.rs#L46-L56被截断的内容会附加[Memory truncated]标记让 Agent 知道信息不完整能力模型最小权限 显式声明WASM 环境下每个胶囊的权限都由 Capsule.toml 显式声明capsule-memory 展示了最小权限的良好实践文件系统仅开放只读能力且限定cwd://与home://两个协议前缀Capsule.toml#L8-L12显式声明allow_prompt_injection true因为它确实要修改提示词Capsule.toml#L14-L15产物是单个astrid_capsule_memory.wasm可执行组件Capsule.toml#L8-L11代码层面同样严格#![deny(unsafe_code)]等 lint 约束见 src/lib.rs#L1-L4。如何构建WASM 极致压缩配置构建命令非常简单cargo build --target wasm32-unknown-unknown --release而 Cargo.toml#L17-L22 的 release 配置值得新手借鉴——opt-level z体积优先、lto true、codegen-units 1、strip true、panic abort配合 cdylib 的 crate 类型Cargo.toml#L9目标是把产物体积压到最小。工具链锁定 Rust 1.94.0 与 wasm32 目标rust-toolchain.toml。新手总结5 分钟看懂记忆注入全链路订阅prompt_builder.v1.hook.before_build事件触发on_before_prompt_build读取home://memory.md个人cwd://{cwd_dir}/memory.md项目缺失即跳过包装分别生成# Memory (personal)与# Memory (project)章节各限 32KB发布向response_topic发布appendSystemContext响应注入提示词构建器把记忆章节追加进系统提示词整套机制仅约 120 行 Rust 代码src/lib.rs却完整展示了事件驱动 Hook、最小权限 Wasm 组件、UTF-8 安全截断三个实用技术点是理解 Agent 系统提示词扩展机制的最佳入门材料 ✨。【免费下载链接】capsule-memoryCross-session memory. Reads local memory state and injects it into the system prompt through hooks. Part of Unicity AOS.项目地址: https://gitcode.com/gh_mirrors/ca/capsule-memory创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考