🧠 pi-everos-memory

给 pi coding agent 的 EverOS 长期记忆层

让 agent 在持续对话中真正「记住你」——跨会话留存偏好、事实、决策与任务经验。

一个纯 TypeScript 的 pi 扩展包：通过 fetch 直连 EverOS REST API， 向 agent 注册 9 个模型可调用工具。以「我与 pi agent 的对话」为入口， 让 agent 越来越了解我，胜任研究员、助教、程序员助手、秘书、编辑、复盘教练等角色。

✨ 特性

• 持久记忆 — 偏好、事实、决策、任务轨迹由 EverOS 跨会话留存，按意图重建上下文。
• 自动消解矛盾 — 信息更新时由 EverOS 自动顶替旧画像，无需手动维护。
• Agent 自判断 — 由模型决定「这轮值得记」才写入，不污染记忆。
• 零依赖加载 — pi 运行时自带核心包，装上即用，无需 npm install。
• 单文件即包 — 仓库根即 pi package，pi install "$PWD" 一键全局接入。

🧰 工具

User 记忆

| 工具 | 说明 | | --- | --- | | memory_search | 检索相关历史上下文、偏好、事实、决策（可选 method/radius/include_original_data） | | memory_add | 把本轮值得长期记住的关键消息写入记忆（可选 attachments 上传本地文件作多模态附件） | | memory_profile | 取回 EverOS 沉淀的用户画像 | | memory_episodes | 按时间倒序列出近期 episode（回顾 / 复盘） | | memory_foresight | 浮现提醒、deadline 等时间敏感项 | | memory_delete | 永久删除：按 MemCell parent_id 删单条，或按 session_id 删整段 |

Agent 记忆

| 工具 | 说明 | | --- | --- | | agent_skills | 取回从过往任务轨迹蒸馏出的可复用技能 | | agent_cases | 取回相似任务的具体过往做法 | | agent_record | 记录一段值得学习的已完成任务轨迹（支持真实 tool_calls/tool 步骤） |

[!NOTE] 写入由 agent 判断（memory_add / agent_record），不每轮强制写入。

[!TIP] 纠正事实优先用 memory_add 写更正说法 —— EverOS 自动消解矛盾、顶替旧画像； 只有要真正抹除数据时才用 memory_delete。单条删除传 MemCell id （memory_search / memory_episodes 结果里的 parent_id，不是 episode / atomic_fact id），返回 204。 删除对权威存储（memory_episodes）立即生效，但 search 索引最终一致、删后可能短暂仍返回该条。

⚙️ 工作原理

pi agent ──tool call──▶ pi-everos-memory ──fetch/HTTPS──▶ EverOS REST API
   ▲                                                            │
   └──────────────── 画像 / episode / 技能 ◀────────────────────┘

工具用 fetch 直连 EverOS REST API（https://api.evermind.ai）。固定参数：单用户 wu、hybrid 检索、assistant 场景模式。pi 运行时自带 @earendil-works/pi-coding-agent、@earendil-works/pi-ai、typebox。

🚀 快速开始

1. 配置 API Key — 在 https://everos.evermind.ai 申请。

npm 安装（推荐） — 密钥放在 pi 用户目录（npm 包内不含 .env）：

echo 'EVEROS_API_KEY="<your_key>"' >> ~/.pi/agent/.env

本地开发（pi install "$PWD"）— 可写在仓库根 .env（已被 .gitignore，不提交）：

echo 'EVEROS_API_KEY="<your_key>"' > .env

查找顺序：EVEROS_API_KEY 环境变量 → 从扩展安装目录向上找 .env → ~/.pi/agent/.env / ~/.config/everos/.env → 从当前工作目录向上找 .env。

2. 安装为 pi package

pi install npm:pi-everos-memory              # 推荐：从 npm 安装（用户级）
# pi install npm:[email protected]    # 固定版本
# pi install -l npm:pi-everos-memory       # 项目级 .pi/settings.json

本地开发（源码留在仓库，pi install 只写入 settings、不复制）：

pi install "$PWD"
# 或 pi install -l "$PWD"

pi list 查看已装包 · pi remove <source> 卸载 · pi config 启用/禁用单项资源。 版本记录见 Releases · pi package 规范。

3. 开聊 — 启动 pi 正常对话即可，agent 会按需 memory_search / memory_add。

🔧 配置

| 环境变量 | 默认值 | 用途 | | --- | --- | --- | | EVEROS_API_KEY | （从 .env 读取） | EverOS 鉴权 | | EVEROS_BASE_URL | https://api.evermind.ai | API base URL |

🛠 开发

npm install        # 仅 typecheck / 测试需要
npm run verify     # typecheck + 测试

📚 文档

| 文件 | 内容 | | --- | --- | | docs/everos.md | EverOS 记忆层设计、工具说明、配置与接入 | | docs/RELEASING.md | npm 与 GitHub Release 发版流程 | | CHANGELOG.md | 版本变更记录 | | AGENTS.md | 模块地图与约定 |

🧭 设计原则

• 单用户、个人使用。
• 记忆存储交给 EverOS，不维护 Markdown 知识库。
• 人定方向、做关键决策与审核；AI 负责检索、总结、草稿、初步分析。

💬 交流

Pull Request · Issue · WeChat qbsdw0616

📄 License

MIT © Mist-wu