Memento-Skills 解读

Memento Skills 解读 背景 仓库地址： 当前定位： 一个以 Skill 为中心 的 Python Agent 框架/产品原型，不只是“技能仓库”。 核心目标： 把 Agent 的能力拆成： LLM 编排 Skill 检索与执行 上下文压缩 会话持久化 GUI / CLI / 飞书桥接 技术栈： Python 3.12、Typer CLI、Flet GUI、LiteLLM、SQLAlc…

10 min read 2876 字

Memento-Skills 解读

背景

  • 仓库地址： https://github.com/Memento-Teams/Memento-Skills
  • 当前定位： 一个以 Skill 为中心 的 Python Agent 框架/产品原型，不只是“技能仓库”。
  • 核心目标： 把 Agent 的能力拆成：
    • LLM 编排
    • Skill 检索与执行
    • 上下文压缩
    • 会话持久化
    • GUI / CLI / 飞书桥接
  • 技术栈： Python 3.12、Typer CLI、Flet GUI、LiteLLM、SQLAlchemy + SQLite、httpx。

从 README 的表述看，它主打的是 Self-Evolving Agent Framework / 自演化智能体框架。但从源码实际实现看，它现在更准确的描述应该是：

一个已经有完整 Agent 主循环、Skill 检索/下载/执行、上下文压缩、会话持久化和 GUI/CLI 壳子的 Skill-first Agent 平台雏形。

也就是说，它不是空壳；但“自演化”这四个字，源码里目前还没有完全闭环到 README 描述的程度。

⚡ TL;DR / 快速结论

我先给结论

  1. 这仓库不是单纯 skills 列表，而是一个完整的本地 Agent 应用骨架。
  2. 它的核心抽象是 SkillGateway / SkillProvider / SkillStore，不是 ToolCall 函数表。
  3. Agent 主循环已经比较清晰：intent -> plan -> execute -> reflect。
  4. 云技能检索 + 自动下载到本地库这条链是真做了，不是 README 口号。
  5. 但“自演化 / 自动优化低效技能 / 自动生成新技能”在核心 runtime 里还没有形成真正自动闭环，更多是通过内置 skill-creator 技能和验证流水线半手工完成。
  6. 如果你从工程视角看，它最值得学的是 Skill-first 架构；如果你从“真自演化 Agent”角度看，它还在早期。

一句话评价

它更像一个“以 Skill 作为一级公民的 Agent OS 雏形”，而不是一个已经完成自我进化闭环的成熟框架。

详细过程

1. 仓库到底是什么

1.1 不是只放技能，而是完整应用

pyproject.toml 直接说明了两件事：

  • 包名：memento-s
  • 版本：0.1.0
  • CLI 入口：memento = cli.main:memento_entry
  • GUI 入口：memento-gui = gui.app:main

依赖也很明显不是“纯 skill 仓库”级别，而是完整本地应用级别：

  • typer, rich → CLI
  • flet → GUI
  • litellm, openai, anthropic, mcp → LLM/模型接入
  • sqlalchemy, aiosqlite, sqlite-vec, alembic → 会话/技能/向量元数据存储
  • httpx → 云技能目录 API

所以这个 repo 本质上是：

一个本地 Python Agent App + Skill 平台 + GUI/CLI 壳 + 云技能同步能力。

2. 核心架构：Skill 是一级公民

这个项目最大的结构特点，是它没有把能力散落成一堆 tool_call -> function。

它把 Skill 做成了完整契约层：

  • core/skill/gateway.py：定义 Agent 依赖的 SkillGateway 协议
  • core/skill/provider.py：真正的 SkillProvider 实现
  • core/skill/store/library.py：磁盘 + DB + embedding 持久化
  • core/skill/schema.py：Skill 领域模型
  • core/skill/retrieval/*：本地 / embedding / 云目录召回

2.1 Agent 只认两个公开工具

在 core/memento_s/tools.py 里，暴露给 LLM 的其实只有两个核心 function tool：

  • search_skill
  • execute_skill

这点很关键，因为它意味着：

Agent 自己不需要认识所有具体能力，它只需要先找技能，再执行技能。

这是一个很明显的 Skill-first Agent 设计，而不是 OpenAI function-call 常见那种“几十个工具全摊在 prompt 里”。

2.2 Skill 有统一执行契约

core/skill/gateway.py 定义了：

  • discover()
  • search()
  • execute()

以及统一返回结构：

  • SkillManifest
  • SkillExecutionResponse
  • SkillStatus
  • SkillErrorCode

这个抽象做得不错，优点是：

  • Agent 只依赖协议，不关心技能来源
  • 本地 skill / 云 skill / builtin skill 都能统一处理
  • 输出有标准 envelope，便于 UI 展示和错误治理

3. Agent 主循环：真的有 plan / execute / reflect

核心主控在：

  • core/memento_s/agent.py

文件头注释已经写得很直接：

  • DIRECT / INTERRUPT -> simple_reply
  • AGENTIC -> plan -> execute -> reflect

3.1 先做意图识别

core/memento_s/phases/intent.py 里先把输入识别成三类：

  • DIRECT
  • AGENTIC
  • INTERRUPT

然后把用户需求规范化成英文任务描述。这个设计说明它希望把：

  • 普通聊天
  • 多步 Agent 执行
  • 中断当前任务

做成显式分流，而不是一锅炖。

3.2 规划阶段比较标准

core/memento_s/phases/planning.py 会生成：

  • TaskPlan
  • PlanStep

失败时退化成单步计划。

这部分没有特别惊艳，但结构清楚：

先把任务拆成可执行 step，再进入每步的 react loop。

3.3 执行阶段是“外层 step + 内层 react”

core/memento_s/phases/execution.py 是这仓库最值得看的文件之一。

它不是简单 while loop，而是：

  • 外层：按计划步骤推进
  • 内层：每一步内部允许多次 react / tool 调用
  • 每一步结束后再做 reflection

这个设计比“每次 tool call 后都立刻反思”更稳，也更像真正的任务执行器。

3.4 Reflection 已经落地

core/memento_s/phases/reflection.py 不是摆设。它会输出：

  • continue
  • replan
  • finalize

也就是说，这个 Agent 不是单纯：

plan -> run完 -> 结束

而是有：

执行 -> 反思 -> 继续/重规划/收尾

这条链已经成型了。

4. 云技能检索 + 自动落本地，这条链是真的

这个仓库最实在的一点，是它真做了云技能目录接入。

4.1 检索策略

core/skill/retrieval/multi_recall.py 的逻辑很直接：

  • 本地技能：全量进入候选
  • 云端技能：通过 RemoteCloudCatalog 搜索 top-k
  • 合并去重：本地优先

4.2 云目录 API

core/skill/retrieval/remote_catalog.py 里定义了两件事：

  • POST /api/v1/search
  • POST /api/v1/download

下载接口返回 github_url，然后再通过 importer 拉到本地。

4.3 首次执行时可自动下载进本地库

core/skill/provider.py 的 _ensure_local_skill() / _download_cloud_skill() 明确做了这件事：

  1. 先查本地
  2. 本地没有就查 cloud catalog
  3. 下载到本地技能目录
  4. load_from_path() 加入本地 cache
  5. add_skill() 写盘 + 写 DB + 可选索引

所以这条用户体验上的主张：

“搜到云技能，第一次执行时自动拉到本地”

从源码上看是成立的。

5. Skill 持久化做得比想象中完整

core/skill/store/library.py + core/skill/store/persistence/writer.py 说明它不只是“内存里有个技能对象”。

它真在做三层同步：

  • 磁盘目录：skills/<skill-name>/SKILL.md + scripts/references/assets
  • 内存缓存：local_cache
  • DB 元数据：技能描述、来源、embedding 等

而且可以：

  • add_skill()
  • remove_skill()
  • refresh_from_disk()
  • sync_all_to_db()
  • cleanup_orphaned_skills()

这说明它是把 Skill 当成“可管理资产”，而不是一次性 prompt 附件。

6. 但 README 里的“自演化”要打个折扣看

这是这仓库最需要你留神的地方。

6.1 它有反思，但不等于自动进化闭环

源码里能确认的，是：

  • 有 reflection
  • 有 replan
  • 有 skill search / execute
  • 有云技能下载
  • 有 skill-creator 内置技能
  • 有 verify / benchmark 流程

但我没有在核心 Agent runtime 里看到这样的自动闭环：

  • 根据失败率自动标记低 utility skill
  • 自动重写 skill 内容
  • 自动生成新 skill
  • 自动把优化结果重新接回主运行时
  • 自动维护技能效用分

也就是说，README 讲的“self-evolving”更像是：

系统设计方向 + 内置工具能力 + 未来路线

而不是现在已经完全由主 Agent 自动完成。

6.2 现在更像“半自动 skill 演化平台”

真正和“造 skill / 改 skill / 评估 skill”强相关的部分，更多在：

  • builtin/skills/skill-creator/
  • cli/commands/verify.py
  • scripts/verify_pipeline.py（由 verify 命令驱动）

这说明它的演化方式更接近：

  • Agent/用户发现能力缺口
  • 借助 skill-creator 创建或优化 skill
  • 用验证流水线评测
  • 再把 skill 纳入库

这个方向是成立的，但它不是“核心 runtime 自动自我修复”的那种全闭环系统。

7. 上下文管理：压缩已接入，长期记忆还没完全接上

7.1 真正接进主链路的是 ContextManager

core/context/manager.py 里已经做了：

  • load_history()：token-aware 历史加载
  • assemble_messages() / assemble_system_prompt()
  • append()：自动 compress / compact
  • persist_tool_result()
  • scratchpad 归档

这说明它在 长会话控制 上不是空白。

7.2 长期记忆模块还处在“半接入”状态

但 core/context/memory.py 的文件头直接写了：

  • TODO: memory 持久化功能暂未接入 ContextManager
  • 当前 ContextManager 不依赖此模块

这点很关键。

所以要分清楚：

  • 已落地： 历史摘要、压缩、scratchpad、上下文 budget
  • 未完全落地： 真正稳定的长期记忆写回与读取注入

也就是说，README 如果把记忆体系讲得非常完整，源码上目前要打一点折扣。

8. 会话与产品外壳：它不是库，而是应用

8.1 GUI 是真产品壳，不是 demo

gui/app.py 说明它做了完整 GUI：

  • Flet UI
  • session sidebar
  • slash commands
  • settings panel
  • update notifier
  • keyboard shortcuts
  • 会话分组与状态展示

这不是“给框架随手包了个页面”，而是明显在做可交互桌面产品。

8.2 CLI 和飞书桥接也都落地了

cli/main.py、cli/commands/feishu_bridge.py 说明它有：

  • CLI 入口
  • verify 批量验证
  • 飞书 WebSocket bridge

特别是飞书桥接，不只是 webhook 收一下消息，而是：

  • sender_id -> session_id 映射
  • DB 会话持久化
  • Agent 回复再回发飞书

这说明它想做的不是本地研究玩具，而是：

带有真实接入面的 Agent 应用层。

9. 工程优点

优点 1：Skill 抽象比很多 Agent 项目更清楚

它没有一上来堆几十个工具，而是用：

  • 搜技能
  • 执行技能

作为统一入口。这种抽象更利于扩展，也利于治理。

优点 2：从“技能对象”到“技能资产”走通了

有：

  • 磁盘目录
  • DB 元数据
  • embedding
  • 云目录
  • 自动下载

这意味着 Skill 不是 prompt 片段，而是可管理资源。

优点 3：Agent 主链路已经有 shape 了

intent / plan / execute / reflect 这套分层是成立的，而且代码组织比较干净。

优点 4：产品壳完整

GUI、CLI、飞书 bridge、verify pipeline 都在，说明团队不是只想做 framework paperware。

10. 风险 / 局限

风险 1：README 的“自演化”容易被过度理解

源码里目前更像：

  • 可反思
  • 可重规划
  • 可扩技能
  • 可半自动优化技能

而不是完全自动的 self-improving skill ecosystem。

风险 2：长期记忆模块还没真正接完

core/context/memory.py 自己就写了 TODO，这意味着“记忆”目前不是闭环强项。

风险 3：云目录默认地址偏工程内网味

middleware/config/system_config.json 里默认的：

  • cloud_catalog_url: http://8.140.204.114:9001/
  • embedding base url 也是裸 IP

这说明当前更像内部部署/实验态，而不是成熟公共 SaaS 形态。

风险 4：版本还很早

0.1.0 本身就说明：

  • 架构方向已形成
  • 但很多“宏大叙事”还在变成工程现实的路上

11. 对你最有价值的点

如果站在你自己的方向（Unity + AI + Agent 工程）看，我觉得它最值得借鉴的不是“自演化”口号，而是这三点：

A. Skill-first，而不是 Tool-list-first

这套思路很适合你以后做：

  • Unity Editor Agent
  • 游戏工程流水线 Agent
  • 知识/文档驱动的开发 Agent

因为它把能力管理从函数调用抬升到了“技能资产层”。

B. 云技能 → 本地缓存 → 持久化 这条链

这个模式很适合你以后做团队技能库或工作室私有能力市场。

C. Plan / execute / reflect 的阶段化结构

虽然不算特别新，但它已经是工程可用的组织方式，比很多 agent demo 强。

12. 我的最终判断

如果只用一句话概括：

Memento-Skills 是一个“以 Skill 为核心抽象”的 Agent 应用框架雏形，基础能力已经做实，但 README 里强调的“自演化”目前更像方向与半自动工具链，而不是完全自动闭环。

所以我给它的定位是：

  • 不是概念项目
  • 也还不是完全成熟框架
  • 是一个方向对、骨架已经成型、值得继续跟踪的早期工程项目

踩坑总结

问题 原因 解决
容易把它看成“skills 列表仓库” 仓库名容易误导 先看 pyproject.toml 和 gui/cli/core 结构
容易把 README 的“自演化”当成已完整实现 宣传语强，容易默认都做完了 一定要核 agent.py、execution.py、reflection.py、skill-creator
容易高估长期记忆能力 memory.py 文件存在，看起来像已经接好了 读文件头 TODO，确认 ContextManager 还没依赖它
容易忽略云技能其实能自动落本地 README 说了但容易当口号 读 provider.py 的 _ensure_local_skill() / _download_cloud_skill()
容易把它当成熟 SaaS 平台 配置里很多裸 IP / 0.1.0 / 内部感很重 把它当早期工程原型看更准确