capsule-memory 部署教程：Rust 编译 WASM 并接入 Astrid OS 的完整流程
【免费下载链接】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
capsule-memory 是 Astrid OS 的跨会话记忆胶囊：它读取本地的memory.md记忆文件，并在每次组装提示词时自动注入系统提示词，让 AI Agent 在多次会话之间"记得"你之前说过什么。本教程带你走完整条链路：用 Rust 把 capsule-memory 编译成 WASM 模块，再接入 Astrid OS 运行。全程只需几条命令，零基础也能跟着做。
一、capsule-memory 是做什么的？
在 Astrid OS 的架构里，这个胶囊相当于操作系统的"持久交换区"——把上下文搬运到会话边界之外。
它的工作机制非常简洁：
- 挂接到
prompt_builder.v1.hook.before_build钩子 - 每次组装提示词时，读取两类记忆文件：
- 个人记忆：
home://memory.md（用户偏好、沟通风格，始终注入） - 项目记忆：
cwd://.astrid/memory.md（项目约定、当前进度，仅项目内注入）
- 个人记忆：
- 把内容包装成
# Memory章节，通过appendSystemContext响应注入系统提示词
文件缺失或为空时，胶囊什么都不做（no-op），所以可以放心部署。
核心逻辑见 src/lib.rs，其中 MAX_MEMORY_BYTES 定义了32KB 硬上限：每段记忆超过 32KB 时会在 UTF-8 字符边界处截断，并追加[Memory truncated]标记，防止无限制吞噬上下文窗口。
二、部署前准备：Rust 环境一键配齐
编译 capsule-memory 只需要一个 Rust 工具链。仓库自带的 rust-toolchain.toml 已锁定好版本和目标：
- Rust 1.94.0（MSRV 1.94）
wasm32-unknown-unknown编译目标（Rust 编写 WASM 的标准目标，输出可在 WASM 运行时中加载）- rustfmt 与 clippy 组件
如果你的机器装了 rustup，进入目录后它会自动按该文件切换工具链。手动确认命令：
rustup target add wasm32-unknown-unknown三、部署步骤：从克隆到接入的完整流程
第 1 步：获取源码
git clone https://gitcode.com/gh_mirrors/ca/capsule-memory cd capsule-memory第 2 步：Rust 编译 WASM（Release 模式）
这是整个部署的关键一步。执行：
cargo build --target wasm32-unknown-unknown --release这条命令告诉 Cargo：以wasm32-unknown-unknown为目标架构做发布构建，产物输出到target/wasm32-unknown-unknown/release/目录。
Cargo.toml 里为 WASM 场景做了专门瘦身——release profile 配置了opt-level = "z"（体积优先压缩）、lto = true（链接期优化）、codegen-units = 1和strip = true，编译出的 WASM 文件会非常小巧，这正是 WASM 模块加载快的原因。
第 3 步：整理胶囊包（Capsule.toml + WASM）
Astrid OS 通过 Capsule.toml 识别胶囊。查看 组件声明：
[[component]] id = "memory" file = "astrid_capsule_memory.wasm" type = "executable" capabilities = { fs_read = ["cwd://", "home://"] }要点：
file字段要求的文件名是astrid_capsule_memory.wasm。Rust 编译出的 cdylib 默认带lib前缀（如libastrid_capsule_memory.wasm），请把它重命名为astrid_capsule_memory.wasm，与Capsule.toml放在一起fs_read能力声明只允许读cwd://和home://，与"只读注入"的设计一致- 权限声明 中
allow_prompt_injection = true是提示词注入能力的开关
然后把整个目录（Capsule.toml+ WASM 文件）放入 Astrid OS 的胶囊目录，OS 启动时即可加载。
第 4 步：写入记忆文件
部署完成后，胶囊每次组装提示词都会扫描两个位置：
| 记忆类型 | 路径 | 用途 |
|---|---|---|
| 个人记忆 | home://memory.md | 用户偏好、长期事实，跨所有项目生效 |
| 项目记忆 | .astrid/memory.md | 当前项目的约定与进度 |
💡 项目目录名
.astrid可通过环境变量cwd_dir覆盖（见 env 配置），品牌定制发行版无需 fork 即可换名。
四、部署验证与常见问题
如何验证成功？在memory.md写入一句话，例如"我偏好简洁的回答"，然后发起一次对话。如果 Agent 的回复体现出这条偏好，说明before_build钩子 → 读取 → 注入的链路已打通。
常见问题速查：
- 📌Agent 完全没"记住"？检查
memory.md是否存在且非空——内容为空时胶囊是静默跳过的，不会报错 - 📌回复末尾出现
[Memory truncated]？说明单段记忆超过 32KB，请精简memory.md，保留最关键的信息 - 📌编译报目标架构错误？确认执行过
rustup target add wasm32-unknown-unknown - 📌WASM 没被加载？确认文件名与 Capsule.toml 的
file字段完全一致
五、总结
回顾一下 capsule-memory 的完整部署链路：
git clone获取源码cargo build --target wasm32-unknown-unknown --release编译 WASM- 重命名为
astrid_capsule_memory.wasm，与Capsule.toml一并放入胶囊目录 - 维护
memory.md，即获得跨会话记忆
整个项目代码量很小（核心仅一个 lib.rs），采用 MIT / Apache 2.0 双许可，既可以直接部署，也适合作为学习"Astrid OS 胶囊如何与系统提示词流水线交互"的最小样例。
【免费下载链接】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），仅供参考
