MemFlywheel

MemFlywheel
让 Agent 把每一次执行，沉淀成下一次更懂你的开始！

English | 简体中文

MemFlywheel 给 Agent Harness 增加一层文件原生记忆飞轮：执行前召回，执行后沉淀，重复工作流演化为 learned skills。

文件原生 Markdown 记忆、source trace 和 learned skills 可检查、可 diff。	渐进召回 从预召回到索引线索、记忆正文和证据逐层读取。
执行后学习 turn-end 提取和 dream 整理让记忆持续流动。	宿主原生 Pi、Hermes、OpenCode 和 OpenClaw 均通过 npm 包接入。

为什么需要

给你的 Agent 装上记忆飞轮：行动前先想起，执行后会沉淀，每一次运行都更懂你。宿主 Agent Harness 管生命周期、模型、鉴权和工具；MemFlywheel 管记忆与学习闭环。

如何工作

Agent Harness
   |
   |  lifecycle / model / auth / tools
   v
MemFlywheel
   |
   |-- pre-recall       -> MEMORY.md 索引线索
   |-- progressive read -> 记忆正文 -> source trace -> learned skills
   |-- turn-end         -> 长期记忆提取
   |-- idle             -> dream 整理与修复
   `-- repeated work    -> 可复用 learned skills

记忆生命周期 召回、提取、整理和证据回溯都围绕文件原生记忆仓库展开。	技能飞轮 重复工作流会演化成 Agent 可检查、可复用的 learned skills。

快速开始

Pi：

pi install npm:@iflytekopensource/adapters

Hermes：

npm install -g @iflytekopensource/hermes
memflywheel-hermes-install
hermes config set memory.provider memflywheel

OpenCode：

opencode plugin @iflytekopensource/adapters --global
opencode run --dir /path/to/project "你的任务"

OpenClaw：

openclaw plugins install npm:@iflytekopensource/adapters
openclaw config set plugins.slots.memory memflywheel
openclaw config set plugins.entries.memflywheel.hooks.allowConversationAccess true
openclaw config set plugins.entries.memflywheel.hooks.allowPromptInjection true
openclaw gateway run --force

MemFlywheel 会作为原生记忆插件接入各宿主。宿主继续负责模型、工具、权限和会话；MemFlywheel 补上召回、 turn-end 提取、dream 整理和 learned skills。

embedding 预召回是可选项。不配置也能正常使用，MemFlywheel 会直接注入最多 200 行生成的 MEMORY.md 索引。记忆索引继续增长后，先启动任意 OpenAI-compatible embeddings endpoint，再在启动宿主前导出这些变量；预召回会自动生效，只注入最相关的索引条目。

export MEMFLYWHEEL_EMBEDDING_ENDPOINT="https://embedding-gateway.example.com/v1"
export MEMFLYWHEEL_EMBEDDING_API_KEY="..."
export MEMFLYWHEEL_EMBEDDING_MODEL="text-embedding-3-small"

宿主配置、embedding 预召回、验证命令和排查路径见 docs/integrations.md。

安装包

Package	作用
@iflytekopensource/adapters	Pi、OpenCode、OpenClaw，以及 Hermes bridge 复用的宿主适配运行层
@iflytekopensource/hermes	Hermes MemoryProvider 安装器和 skill 镜像

内部 workspace 包按职责拆代码；普通用户只安装自己宿主需要的包。

评测

MemFlywheel 使用面向 LoCoMo 的回归检查，让长期记忆能力在召回、提取和 learned skill 闭环演进时可衡量。详见 docs/evaluation.md。

文档

文档	内容
docs/architecture.md	存储布局、召回、提取、dream、技能闭环、包边界
docs/integrations.md	Pi、Hermes、OpenCode、OpenClaw、embedding 预召回、SDK hooks、adapter 边界
docs/evaluation.md	LoCoMo 定位和本地回归检查
docs/release.md	版本规范、npm 发布渠道、发布检查清单
CHANGELOG.md	公开 npm 包版本变更记录
NOTICE、THIRD_PARTY_LICENSES	项目版权告知和三方 license 披露

开源边界

MemFlywheel 的目标是成为 Agent Harness 里的长期记忆和技能学习基础组件。它保持文件原生、模型无关、宿主优先，不把主 Agent、模型服务、工具权限或技能执行吞进自己内部。