agent-self-evolution

The agent that grows with you. 一个让 AI 编程助手从每次任务中自动学习、沉淀经验、进化技能的开源系统。

agent-self-evolution 借鉴 Hermes Agent Self-Evolution 的设计哲学，为 AI 编码助手（pi / Claude Code / Codex）打造一套完整的「经验 → 技能 → 进化」学习闭环：

每次任务结束后，系统在后台安静地分析会话轨迹，把值得复用的经验自动草拟成技能候选；
你手动说一句「总结一天的工作」或「进化」，系统就会审查候选、启用好技能、维护长期记忆、沉淀踩坑教训；
日积月累，你的 agent 会越来越懂你的环境、你的工具链、你踩过的每一个坑。

为什么需要它

AI 编码助手是无状态的：一次任务中学到的经验，下次任务就忘了。常见痛点：

痛点	现状	本系统的解法
同样的坑反复踩	每次排错都从零开始	踩坑经验沉淀进 `LESSONS.md`，下次直接查证
复杂流程无法复用	部署/排错步骤散落在对话历史里	自动草拟成 SKILL.md 技能，随时调用
用户偏好记不住	每次都要重新叮嘱	用户画像 `USER.md` 持续维护
技能库膨胀失控	装了一堆技能不知道哪些还有用	使用统计 + 健康度反馈 + 归档机制，三级体检
记忆不可追溯	改了什么、为什么改，无从查起	明文文件 + 经验日志 + git 历史

工作原理

        ┌─────────────────────────────────────────────────────────┐
        │                        一次任务                         │
        └──────────────────────────┬──────────────────────────────┘
                                   ▼
        ┌─────────────────────────────────────────────────────────┐
        │   [采集器] 任务结束后后台分析轨迹（hook 自动触发）          │
        │   统计工具调用 / 错误修复 → 满足条件？                     │
        │   → 低成本 LLM 调用，草拟 SKILL.md 候选                   │
        └──────────────────────────┬──────────────────────────────┘
                                   ▼
        ┌─────────────────────────────────────────────────────────┐
        │   candidates/ 候选区（未启用，不进上下文）                 │
        │   增量采集：同一会话可多次采集，不丢数据                    │
        └──────────────────────────┬──────────────────────────────┘
                                   ▼  （你手动说一句「进化」）
        ┌─────────────────────────────────────────────────────────┐
        │   [进化流程] 审查候选 → 格式校验 → 查重 → 价值评估         │
        │   启用（软链）/ 并入现有 / 淘汰（记录原因）                 │
        │   技能体检（闲置/问题/优质三级）→ 归档 / 修复 / 保留      │
        │   维护记忆（USER.md / LESSONS.md）→ git 提交             │
        └──────────────────────────┬──────────────────────────────┘
                                   ▼
        下次任务 ←────── 已启用的技能进入上下文，经验生效

核心设计哲学：采集与进化完全解耦。

采集是全自动的、安静的、低成本的——只负责「记下来」，从不打扰你；
进化是完全手动的——只有你说「进化」，系统才会花 token 深度审查、启用技能、更新记忆；
候选技能在启用前永不进入上下文，天然隔离了「自动生成内容」对运行环境的污染。

支持平台

平台	采集	使用统计	进化流程	记忆注入	状态
pi (pi-coding-agent)	扩展 `self-evolve.ts`（监听 `agent_settled`）	扩展 `skill-usage.ts`（agent_settled）	技能 `self-evolve`（`/skill:self-evolve`）	软链注入 / 文档引用	✅ 完整支持
Claude Code	`Stop` hook（读取 transcript）	`core/track_usage.py`（hook 调用）	`CLAUDE.md` 流程文档	`@memory/USER.md` 引用	✅ 支持
Codex (OpenAI Codex CLI)	`Stop` hook（读取 session 轨迹）	`core/track_usage.py`（hook 调用）	`AGENTS.md` 流程文档	`@memory/USER.md` 引用	✅ 支持

兼容性说明：采集器核心（core/collect.py）与平台无关；各平台只负责「把轨迹归一化成统一 JSONL」+「注册 hook」。因此理论上任何「有 transcript、支持 hooks、能调 LLM」的 agent 都能接入。

各平台成熟度差异

Pi：最完整——采集使用 pi 自身的模型注册表，无需额外 API Key；使用统计走 TS 扩展；技能启用走 pi 原生软链机制；进化流程可随时通过 /skill:self-evolve 触发。
Claude Code：采集走 Stop hook + claude -p headless 调用（复用登录态）；使用统计由 hook 调用 core/track_usage.py；进化流程通过 CLAUDE.md 注入。
Codex：采集走 Stop hook + codex exec（复用登录态）；使用统计同 Claude Code；注意 Codex 的 transcript 格式在不同版本间变化较大（v0.14x 起为 response_item 包裹结构），归一化脚本做了新旧格式兼容，但仍以你本机实测为准。

快速开始

推荐：不要自己一步步装，直接把下面这段复制发给你的 AI 助手（pi / Claude Code / Codex 都行），让它代劳。完整安装指引见 INSTALL.md。

请帮我安装 agent-self-evolution（让 AI 助手自动沉淀技能与记忆的开源系统）：
1. 检测环境（pi / claude / codex 装了哪些，python3 是否可用）
2. git clone https://github.com/Shiorangerin/agent-self-evolution.git
3. 按检测结果运行 bash install.sh pi / claude-code / codex / all
4. 验证 ~/.config/agent-self-evolution/ 初始化完成，报告结果

手动安装：

git clone https://github.com/Shiorangerin/agent-self-evolution.git
cd agent-self-evolution
bash install.sh        # 或 bash install.sh pi / claude-code / codex / all

首次使用

# 跑一个多步骤任务（工具调用 ≥5 次），然后：
ls ~/.config/agent-self-evolution/candidates/   # 看是否出现了候选技能

# 对你的 agent 说： 「总结一天的工作」 或 「进化」

核心概念详解

数据目录（`$SE_ROOT`，默认 `~/.config/agent-self-evolution/`）

路径	用途
`candidates/`	候选技能区：采集器自动生成的 SKILL.md 草稿，未被启用前不进上下文
`skills/`	已启用的技能源文件（Pi 上通过软链挂到技能加载目录生效）
`archived/`	归档技能（从上下文消失但源文件保留）
`memory/USER.md`	长期记忆：用户画像、偏好、习惯
`memory/LESSONS.md`	长期记忆：踩坑经验、失败教训、规避方法
`logs/experience-log.md`	经验沉淀日志：每次沉淀的来源、结论、去向，可追溯
`logs/session-summaries/`	每日工作总结存档
`logs/archive/`	按月归档的历史经验日志（主日志超限后自动归档）
`state.json`	系统状态：统计计数、上次进化/采集时间、拒绝原因
`usage.json`	技能使用统计（强/弱信号 + 成功/失败/未知结果归因 + 失败原因）
`core/`	平台无关核心（collect.py / track_usage.py / init.py / templates）

候选（Candidate）

采集器判定「值得沉淀」的标准（满足其一即可）：

这类任务以后会重复出现（部署、排错、特定工具链、多步骤流程）；
轨迹里有明确的步骤、经验、坑点可以复用；
不是一次性的琐碎问答。

触发阈值：单次任务工具调用 ≥5 次，或出现错误并修复。可通过 SE_MIN_TOOL_CALLS 调整。

审查（Review）

进化流程对每个候选执行三步校验：

格式校验：name（小写字母数字连字符）、description（≤1024 字符、写明何时使用）、SKILL.md ≤5000 字符；
查重：与已启用技能语义重复 → 并入或淘汰；
价值评估：会重复出现吗？步骤可复用吗？有真实坑点吗？

启用 / 归档

启用 = 候选移入 skills/ + 建立软链 + 记录日志（Pi 上还需要软链到 ~/.pi/agent/skills/）；
归档 = 技能从上下文消失，源文件保留在 archived/，随时可恢复；
所有操作都写入 experience-log.md 并在 git 中留痕，可回滚。

记忆体系

文件	内容	注入方式
`USER.md`	用户偏好、习惯、禁忌	Pi 注入系统提示 / Claude Code、Codex 用 `@` 引用
`LESSONS.md`	踩坑经验（场景/现象/根因/解法/来源）	按需读取

优势：为什么值得用

1. 经验不流失，agent 真正「越用越懂你」

这是最核心的价值。每次任务后，可复用的流程、踩过的坑、总结出的解法都被结构化沉淀。半年后你的 agent 拥有一个为你量身定制的私有技能库，而不是每次从零推理。

2. 零打扰的采集设计

采集在任务结束后后台进行，不打断你的工作流；
候选技能不进上下文，不污染后续任务的输入；
失败全部静默处理，最多在日志里留一行原因。

3. 成本可控（省 token 设计）

采集只做低成本判断：轨迹摘要截断（默认 2500 字符）、低推理强度（reasoningEffort: minimal）、输出预算受限（2000 tokens）、无缓存开销；
增量采集：同一会话只分析上次采集点之后的新内容，长程对话不重复花钱；
节流与上限：全局节流可配置（默认关闭，因为增量采集不丢数据）、候选区堆积上限 20 个自动暂停；
深度进化（候选审查、技能重构）只在你手动触发时发生。

4. 完全手动触发，你永远拥有控制权

没有任何自动定时、自动唤醒。你说「进化」它才进化。这是刻意的设计：AI 不应该在你不注意的时候改变自己的行为。

5. 候选制安全护栏（核心安全设计）

自动生成的内容永不直接生效：采集器只负责草拟，任何技能都必须经过你触发的审查流程才能启用。即使 LLM 草拟了危险或有毒的内容，它也只会安静躺在 candidates/ 里，不会进入你的 agent 上下文。

6. 透明、可追溯、可回滚

一切以明文文件存在，你可以随时用编辑器查看、修改、删除任何一条记忆；
每次沉淀、启用、淘汰、归档都写入经验日志；
数据目录可纳入 git 仓库，每一次变化都有 commit，一键回滚。

7. 跨平台，一份经验多处复用

同一套数据目录可以被 Pi、Claude Code、Codex 共享。你在 Pi 上沉淀的技能，在 Codex 里同样可用（反之亦然）。切换工具不丢失积累。

8. 技能健康管理（不膨胀、能辨好坏）

usage.json 使用统计（纯规则、零 LLM 成本）为每个技能记录使用信号，并对真正读取过技能文件的会话做结果归因（成功/失败/未知，附失败原因原文片段）：失败信号来自技能使用后的报错或用户负面反馈。

进化流程定期做「技能体检」，分三级处置：

闲置技能：≥60 天未使用 → 由你决定归档或保留；
问题技能：失败 ≥2 次或失败率 >50% → 自动复核失败原因，能补坑点就补、步骤错了就修，屡败零胜建议淘汰；
优质技能：多次使用且零失败 → 确认保留。

技能总量控制在 ~40 个以内，避免上下文被 description 淹没。

9. 增量采集不丢数据

即使上次采集被节流或失败，下次触发时也会从上次的位置继续分析，只延迟、不丢失。

10. 失败可诊断

所有被拒绝的采集都有原因记录（state.json 的 rejections + logs/experience-log.md，原因含 LLM 返回的错误信息）。系统「静默但不黑盒」。

11. 轻量、零第三方依赖

核心采集器仅用 Python 标准库，无 pip 依赖、无 node_modules；hook 脚本是纯 bash + python3。安装、迁移、卸载都极其简单。

12. 启发自 Hermes，但为日常使用打磨

借鉴 Hermes Agent Self-Evolution 的「反思引擎 + 技能自动生成」哲学，但针对真实日常使用做了大量工程化取舍：手动触发、候选制、增量采集、token 预算、查重保险丝、格式校验等（详见 docs/DESIGN.md）。

风险与注意事项（请务必阅读）

本节是极其重要的诚实披露。任何「自动学习」系统都有代价，请在使用前完整阅读并评估。

R1. Token 与 API 成本（确定性风险）

每次满足触发条件的任务（≥5 次工具调用或出现错误）都会产生一次 LLM 调用，虽然成本经过控制（低推理强度 + 截断 + 输出限制），但不是零成本；
高频使用下（每天几十个任务），每天会产生几十次低成本调用，每月累计可能达到数美元级别（取决于你的模型定价）；
控制手段：调高 SE_MIN_TOOL_CALLS、设置 SE_THROTTLE_MS 节流、调低 SE_MAX_OUTPUT_TOKENS、用更便宜的模型做采集（如通过 SE_LLM_CMD 指定）、或直接卸载扩展停止采集；
进化流程（手动触发）的一次深度审查可能消耗较多 token，这是预期行为。

R2. 隐私与数据外泄（确定性风险，需你主动规避）

采集器会把会话轨迹摘要（用户请求、执行过的命令、错误输出，默认截断到 2500 字符）发送给 LLM 提供方；
摘要可能包含：文件路径、命令内容、代码片段、甚至敏感信息（token、密钥、隐私内容）——如果它们出现在你的会话里；
缓解措施：
- 敏感项目里请调低采集阈值或直接禁用采集（删除/停用 hook）；
- 使用自托管/私有模型作为采集后端（SE_API_BASE 指向私有端点）；
- 定期检查 candidates/，确认没有敏感内容；
- 数据目录（$SE_ROOT）不要推到公共仓库——它包含你的轨迹来源与记忆。
除 LLM 调用外，系统所有数据都存储在本地明文文件中，不上传任何云端。

R3. LLM 幻觉与错误技能（中概率风险，已有缓解）

采集器草拟的技能可能包含虚构的 API、命令、步骤（LLM 幻觉），历史上确实发生过（如草拟出不存在的扩展 API）；
缓解：候选制（不直接生效）+ 你触发的审查流程（格式校验/查重/价值评估）+ 代码层查重保险丝；
残余风险：审查流程本身依赖 agent 的判断。审查时请重点核对候选中的命令、路径、API 是否真实存在。

R4. 记忆污染（低概率、高影响风险）

USER.md 如果注入系统提示，其中的错误条目会持续影响 agent 的行为，且难以察觉；
自动沉淀的记忆可能误解你的偏好（把一次性偏好当成长期偏好）；
缓解：记忆条目由进化流程人工审查后写入；建议定期抽查 USER.md；注入内容遵守「纯净」规范（无元信息噪音）；
由于文件是明文，你随时可以手动修正或清空。

R5. 上下文污染与技能膨胀（可管理风险）

启用技能过多 → description 列表本身占上下文、互相干扰；
缓解：40 个上限 + 三级体检（闲置/问题/优质）+ 归档机制；
需要你主动参与归档决策。

R6. hooks 的性能与可靠性影响（低风险）

每次任务结束，hook 会执行：读 transcript + 归一化 + （满足条件时）LLM 调用；
LLM 调用可能让任务结束多等几秒到几十秒（最长 600s 超时）；
hook 全程容错、恒 exit 0：采集失败不会阻塞或干扰 agent；
极端情况下（如 claude -p 挂起）可能延迟任务结束，遇到时可考虑提高节流或换更快的后端。

R7. 文件操作风险（软链 / 移动 / 删除）

启用的技能涉及 mkdir/cp/ln，归档涉及 mv/unlink；
万一误操作（如软链指错位置），可能影响技能加载；
缓解：git 提交可回滚 + 经验日志可追溯 + 软链结构简单可手工修复。

R8. git 仓库噪音与误提交

进化流程会在数据目录所在的 git 仓库自动提交；
如果 $SE_ROOT 位于你已有的项目仓库里，自动提交会混入项目历史；
建议：为 $SE_ROOT 单独建一个私有 git 仓库（或让 ~/.config 下的目录独立管理），避免与项目仓库混淆。

R9. 兼容性漂移（平台风险）

Claude Code / Codex 的 transcript 格式、hook 协议、settings 结构会随版本变化；
Codex 的 transcript 格式尤其不稳定（新旧格式差异大）；
本项目对已知格式做了兼容处理，但不保证未来版本不破坏；
缓解：失败静默 + 日志记录；发现问题时到仓库提 issue。

R10. 日志可能包含敏感信息

state.json 的 rejections 记录了拒绝原因（可能提及敏感细节）；
这些文件默认留在本地，不要提交到公共仓库；可随时删除。

R11. 依赖外部登录态

采集 LLM 调用复用 claude / codex CLI 的登录态（或你配置的 API Key）；
如果这些 CLI 未登录/未安装，采集会静默失败（记录 rejection），系统其余部分不受影响；
建议：至少配置一种 LLM 后端（见 LLM 后端）。

R12. 这不是「自动调参/自动改写人格」系统

本系统只沉淀技能与记忆，绝不自动修改你的 AGENTS.md、人格文件、规则文件；
如果你期望的是「AI 自动进化自己的系统提示」，这不是本项目做的事（也不建议任何系统这么做）。

安全与隐私模型

详见 docs/SECURITY.md。要点：

数据本地化：除 LLM 采集调用外，全部数据本地明文存储；
最小权限：hook 只读 transcript、只写 $SE_ROOT；不触碰其他文件；
候选隔离：自动生成内容永不直接生效；
可禁用：删除 hook 配置或卸载扩展即可完全停止采集，不影响 agent 本体；
透明：所有状态可读、可改、可删、可回滚。

配置项

环境变量	默认值	说明
`SE_ROOT`	`~/.config/agent-self-evolution`	数据根目录
`SE_MIN_TOOL_CALLS`	`5`	采集触发的工具调用阈值
`SE_MAX_CANDIDATES`	`20`	候选区堆积上限（超过暂停采集）
`SE_MAX_TRACE_CHARS`	`2500`	轨迹摘要截断长度
`SE_MAX_OUTPUT_TOKENS`	`2000`	LLM 草拟输出预算
`SE_THROTTLE_MS`	`0`	全局节流（毫秒；默认关闭）
`SE_LLM_CMD`	无	自定义 LLM 调用命令，用 `{prompt}` 占位（如 `my-llm "{prompt}"`）
`SE_API_BASE`	无	OpenAI 兼容 API 地址（如 `https://api.example.com/v1`）
`SE_API_KEY`	无	OpenAI 兼容 API Key
`SE_API_MODEL`	无	OpenAI 兼容 API 模型名

LLM 后端

采集器自动按以下优先级探测（core/collect.py）：

SE_LLM_CMD（自定义命令，最灵活）；
claude CLI（claude -p，复用 Claude Code 登录态）；
codex CLI（codex exec，复用 Codex 登录态）；
SE_API_BASE + SE_API_KEY + SE_API_MODEL（OpenAI 兼容 API）。

全部不可用时采集静默失败（记录原因），不影响 agent 正常工作。

常见问题 FAQ

Q：采集会拖慢我的任务吗？ A：采集在任务结束后异步执行，hook 超时 600s。正常情况下只增加几秒延迟；若你的模型很慢，可调高节流或换快模型。

Q：候选技能什么时候生效？ A：永远不自动生效。只有你触发进化流程并审查通过后才会启用。

Q：我不想让某个项目被采集？ A：临时方案：把 SE_MIN_TOOL_CALLS 调高；彻底方案：删除该平台的 hook 配置。也可以删除 $SE_ROOT 中的候选与日志。

Q：切换平台后，之前的记忆还在吗？ A：在。数据目录是共享的，Pi / Claude Code / Codex 读同一份 $SE_ROOT。

Q：如何完全卸载？ A：1) 删除 hook 配置（Claude Code 的 settings.json 中的 Stop 条目 / Codex 的 hooks.json）；2) 删除 Pi 扩展文件；3) 删除 $SE_ROOT 目录。不残留任何后台进程。

Q：采集用的模型能单独指定吗？ A：能。SE_LLM_CMD 可指定任意命令/模型；Pi 平台则用 pi 当前模型（可临时切换）。

Q：技能格式有要求吗？ A：frontmatter 要求 name（小写字母数字连字符）+ description（≤1024 字符，写明何时使用）；正文 ≤5000 字符。这是审查流程的硬性校验。

Q：为什么不用自动定时进化？ A：刻意设计。自动唤醒会反复打断你、消耗 token、并可能在你不知情时改变 agent 行为。手动触发 = 完全控制。

与 Hermes 的关系

本项目受 Hermes Agent Self-Evolution 启发（反思引擎 + 技能自动生成 + 候选审查的哲学），但独立实现，并针对真实日常使用做了关键取舍：

维度	Hermes	本项目
触发方式	自动化为主	完全手动触发（用户控制）
候选生效	自动审查流水线	候选制 + 手动进化审查
上下文影响	技能直接进上下文	未启用候选永不进上下文
成本控制	-	增量采集 + 低推理强度 + 节流 + 上限
平台	自有 agent	Pi / Claude Code / Codex 三平台

贡献

欢迎 PR / Issue

Name		Name	Last commit message	Last commit date
Latest commit History 5 Commits
core		core
docs		docs
platforms		platforms
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
INSTALL.md		INSTALL.md
LICENSE		LICENSE
README.md		README.md
install.sh		install.sh

Folders and files

Latest commit

History

Repository files navigation