Skip to content

refactor: unify host-native memory agents and npm package #45

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
dongjiang1989 merged 7 commits into from
Jul 28, 2026
Merged

refactor: unify host-native memory agents and npm package #45

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
06bc9e1
refactor: unify host-native memory agents
OLDyade Jul 28, 2026
17ce1b2
refactor: publish a single MemFlywheel package
OLDyade Jul 28, 2026
3fdc7f1
test: isolate the Hermes installer contract
OLDyade Jul 28, 2026
99d73cb
ci: use the current examples smoke entrypoint
OLDyade Jul 28, 2026
29f2d37
docs: restore unreleased changelog entries
OLDyade Jul 28, 2026
0c05657
Merge remote-tracking branch 'upstream/main' into fix/host-native-mod…
OLDyade Jul 28, 2026
5f6fc94
docs: preserve the full E2E changelog details
OLDyade Jul 28, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/ISSUE_TEMPLATE/bug_report.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ assignees: ""

## Package

`@iflytekopensource/adapters` / `@iflytekopensource/hermes` / internal workspace
`@iflytekopensource/memflywheel` / internal workspace

## Environment

Expand Down
6 changes: 1 addition & 5 deletions .github/workflows/ci.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -84,11 +84,7 @@ jobs:

- name: Examples smoke test
if: matrix.os == 'ubuntu-latest' && matrix.node-version == '22'
run: |
USE_FAKE=1 node examples/pi/run.mjs
USE_FAKE=1 node examples/hermes/run.mjs
USE_FAKE=1 node examples/openclaw/run.mjs
USE_FAKE=1 node examples/learning-loop/run.mjs
run: pnpm --dir examples smoke

- name: Pack dry run
if: matrix.os == 'ubuntu-latest' && matrix.node-version == '22'
Expand Down
5 changes: 2 additions & 3 deletions .github/workflows/e2e.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,11 +43,10 @@ jobs:
- name: Build
run: pnpm run build

- name: Pack memflywheel packages
- name: Pack memflywheel package
run: |
mkdir -p e2e/packages
pnpm --filter @iflytekopensource/adapters pack --pack-destination e2e/packages/
pnpm --filter @iflytekopensource/hermes pack --pack-destination e2e/packages/
pnpm --filter @iflytekopensource/memflywheel pack --pack-destination e2e/packages/
ls -la e2e/packages/

- name: Install kind
Expand Down
2 changes: 1 addition & 1 deletion .github/workflows/preview-release.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,4 +39,4 @@ jobs:
run: pnpm run build

- name: Publish preview
run: pnpx pkg-pr-new publish packages/adapters packages/hermes-plugin
run: pnpx pkg-pr-new publish packages/memflywheel
34 changes: 31 additions & 3 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,17 +7,45 @@ for published packages.

## [Unreleased]

## [0.1.1] - 2026-07-28

### Added

- Kubernetes-level E2E CI workflow using kind and agent-sandbox CRDs. Deploys

@dongjiang1989 dongjiang1989 Jul 28, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@OLDyade Miss this chang docs

@OLDyade OLDyade Jul 28, 2026 •
edited
Loading

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Restored the missing changelog entries with the current scope: the kind + agent-sandbox E2E covers Pi, Hermes, and OpenClaw, and the docs cover the 200-line direct-index limit and optional embedding setup. Commit: 29f2d37. The branch is already based on the latest main. Please re-review.

@dongjiang1989 dongjiang1989 Jul 28, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please double-check. At minimum, there is missing information in changelog.md. @OLDyade

@OLDyade OLDyade Jul 28, 2026

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Double-checked and fixed. I merged the latest main (including the DeepWiki badges) and restored the full changelog details: separate namespaces, custom images, full lifecycle validation, and offline/no-key execution. I only updated the host scope to include OpenClaw and the package wording to match the unified package. Commits: 0c05657, 5f6fc94. Please re-review.

Pi and Hermes agents in separate namespaces with memflywheel packages baked
into custom Docker images, then validates the full memory lifecycle against
a mock LLM (offline, no API key required).
Pi, Hermes, and OpenClaw agents in separate namespaces with the MemFlywheel
package baked into custom Docker images, then validates the full memory
lifecycle against a mock LLM (offline, no API key required).
- Optional embedding pre-recall for large `MEMORY.md` indexes, configured through
OpenAI-compatible embedding endpoint, API key, model, batch size, and retrieval
limit environment variables.
- Documentation for the 200-line direct index limit and the optional
endpoint/API-key setup needed to enable pre-recall.
- Hermes host-write guard and learned-skill synchronization for native host
integration.

### Changed

- Consolidated the former `@iflytekopensource/adapters` and
`@iflytekopensource/hermes` distributions into the single public
`@iflytekopensource/memflywheel` package for all four hosts.
- Unified extraction, dream, and skill evolution on Pi Agent Core with
host-resolved `pi-ai` model bindings.
- Reused each host's active model, endpoint, credentials, headers, protocol, and
provider options across Pi, OpenCode, Hermes, and OpenClaw.
- Replaced the internal provider-neutral model package with the optional
embeddings package and provider-native transports.
- Moved cross-process memory locking to `proper-lockfile` and raised the Node.js
requirement to 22.19.

### Fixed

- Preserved provider-native assistant replay fields across multi-step tool loops.
- Made OpenCode turn completion and idle delivery serial and idempotent, while
supporting OpenAI-compatible, Responses, Anthropic, Google, Bedrock, and
Mistral transports without silent protocol fallback.
- Reused OpenCode and Pi host credentials on every background model turn.
- Declared the OpenClaw plugin API as a compatible semver floor so current
OpenClaw releases can install the package.

### Security

Expand Down
14 changes: 7 additions & 7 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,13 +21,13 @@ pnpm run ci

Please keep changes inside the public MemFlywheel scope:

| Area | Rule |
| --------- | -------------------------------------------------------------------------------------------------------------------- |
| Storage | Markdown files plus YAML frontmatter are the source of truth. |
| Index | `MEMORY.md` is a rebuildable index. Do not hand-edit it. |
| Recall | Full-index recall only. Do not add embeddings, BM25, top-k, or vector search. |
| LLM calls | `@memflywheel/core` must not call LLMs directly. Use injected runners or `@memflywheel/model` canonical model ports. |
| Naming | Use `MemFlywheel`, `memflywheel`, `@memflywheel/*`, and `MEMFLYWHEEL_*`. |
| Area | Rule |
| --------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| Storage | Markdown files plus YAML frontmatter are the source of truth. |
| Index | `MEMORY.md` is a rebuildable index. Do not hand-edit it. |
| Recall | Full-index recall only. Do not add embeddings, BM25, top-k, or vector search. |
| LLM calls | `@memflywheel/core` must not call LLMs directly. Write-side tasks use the SDK's Pi Agent Core runner and host-resolved pi-ai bindings. |
| Naming | Use `MemFlywheel`, `memflywheel`, `@memflywheel/*`, and `MEMFLYWHEEL_*`. |

## Pull Requests

Expand Down
27 changes: 13 additions & 14 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,11 +14,11 @@
</p>

<p align="center">
<a href="https://www.npmjs.com/package/@iflytekopensource/adapters"><img alt="npm" src="https://img.shields.io/npm/v/%40iflytekopensource%2Fadapters?label=npm"></a>
<a href="https://www.npmjs.com/package/@iflytekopensource/adapters"><img alt="npm downloads" src="https://img.shields.io/npm/dm/%40iflytekopensource%2Fadapters?label=downloads"></a>
<a href="https://www.npmjs.com/package/@iflytekopensource/memflywheel"><img alt="npm" src="https://img.shields.io/npm/v/%40iflytekopensource%2Fmemflywheel?label=npm"></a>
<a href="https://www.npmjs.com/package/@iflytekopensource/memflywheel"><img alt="npm downloads" src="https://img.shields.io/npm/dm/%40iflytekopensource%2Fmemflywheel?label=downloads"></a>
<a href="https://github.com/iflytek/memflywheel/releases"><img alt="release" src="https://img.shields.io/github/v/release/iflytek/memflywheel?include_prereleases&label=release"></a>
<a href="https://github.com/iflytek/memflywheel/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/iflytek/memflywheel/actions/workflows/ci.yml/badge.svg"></a>
<img alt="node" src="https://img.shields.io/badge/node-%3E%3D22.13.0-339933">
<img alt="node" src="https://img.shields.io/badge/node-%3E%3D22.19.0-339933">
<a href="LICENSE"><img alt="license" src="https://img.shields.io/github/license/iflytek/memflywheel"></a>
<a href="https://deepwiki.com/iflytek/memflywheel"><img alt="Ask DeepWiki" src="https://deepwiki.com/badge.svg"></a>
</p>
Expand All @@ -36,7 +36,7 @@ skills.
</tr>
<tr>
<td><strong>Post-run learning</strong><br>Turn-end extraction and dream consolidation keep memory moving.</td>
<td><strong>Harness-native</strong><br>Pi, Hermes, OpenCode, and OpenClaw are supported through npm packages.</td>
<td><strong>Harness-native</strong><br>Pi, Hermes, OpenCode, and OpenClaw are supported through one npm package.</td>
</tr>
</table>

Expand Down Expand Up @@ -78,28 +78,28 @@ MemFlywheel
Pi:

```sh
pi install npm:@iflytekopensource/adapters
pi install npm:@iflytekopensource/memflywheel
```

Hermes:

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

OpenCode:

```sh
opencode plugin @iflytekopensource/adapters --global
opencode plugin @iflytekopensource/memflywheel --global
opencode run --dir /path/to/project "your task"
```

OpenClaw:

```sh
openclaw plugins install npm:@iflytekopensource/adapters
openclaw plugins install npm:@iflytekopensource/memflywheel
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
Expand All @@ -125,15 +125,14 @@ export MEMFLYWHEEL_EMBEDDING_MODEL="text-embedding-3-small"
Host setup, embedding pre-recall, verification, and troubleshooting live in
[`docs/integrations.md`](docs/integrations.md).

## Install Packages
## Install Package

| Package | Role |
| ------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------- |
| [`@iflytekopensource/adapters`](https://www.npmjs.com/package/@iflytekopensource/adapters) | Pi, OpenCode, OpenClaw, and the shared host-adapter runtime used by Hermes |
| [`@iflytekopensource/hermes`](https://www.npmjs.com/package/@iflytekopensource/hermes) | Hermes MemoryProvider installer and skill mirror |
| Package | Role |
| ------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------- |
| [`@iflytekopensource/memflywheel`](https://www.npmjs.com/package/@iflytekopensource/memflywheel) | Pi, Hermes, OpenCode, and OpenClaw integrations, including the Hermes MemoryProvider installer and skill mirror |

Internal workspace packages keep the code split by responsibility; users install
only the host package they need.
the same public package for every supported host.

## Evaluation

Expand Down
25 changes: 12 additions & 13 deletions README.zh.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,11 +14,11 @@
</p>

<p align="center">
<a href="https://www.npmjs.com/package/@iflytekopensource/adapters"><img alt="npm" src="https://img.shields.io/npm/v/%40iflytekopensource%2Fadapters?label=npm"></a>
<a href="https://www.npmjs.com/package/@iflytekopensource/adapters"><img alt="npm downloads" src="https://img.shields.io/npm/dm/%40iflytekopensource%2Fadapters?label=downloads"></a>
<a href="https://www.npmjs.com/package/@iflytekopensource/memflywheel"><img alt="npm" src="https://img.shields.io/npm/v/%40iflytekopensource%2Fmemflywheel?label=npm"></a>
<a href="https://www.npmjs.com/package/@iflytekopensource/memflywheel"><img alt="npm downloads" src="https://img.shields.io/npm/dm/%40iflytekopensource%2Fmemflywheel?label=downloads"></a>
<a href="https://github.com/iflytek/memflywheel/releases"><img alt="release" src="https://img.shields.io/github/v/release/iflytek/memflywheel?include_prereleases&label=release"></a>
<a href="https://github.com/iflytek/memflywheel/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/iflytek/memflywheel/actions/workflows/ci.yml/badge.svg"></a>
<img alt="node" src="https://img.shields.io/badge/node-%3E%3D22.13.0-339933">
<img alt="node" src="https://img.shields.io/badge/node-%3E%3D22.19.0-339933">
<a href="LICENSE"><img alt="license" src="https://img.shields.io/github/license/iflytek/memflywheel"></a>
<a href="https://deepwiki.com/iflytek/memflywheel"><img alt="Ask DeepWiki" src="https://deepwiki.com/badge.svg"></a>
</p>
Expand All @@ -34,7 +34,7 @@ MemFlywheel 给 Agent Harness 增加一层文件原生记忆飞轮：执行前
</tr>
<tr>
<td><strong>执行后学习</strong><br>turn-end 提取和 dream 整理让记忆持续流动。</td>
<td><strong>宿主原生</strong><br>Pi、Hermes、OpenCode 和 OpenClaw 均通过 npm 包接入。</td>
<td><strong>宿主原生</strong><br>Pi、Hermes、OpenCode 和 OpenClaw 均通过同一个 npm 包接入。</td>
</tr>
</table>

Expand Down Expand Up @@ -74,28 +74,28 @@ MemFlywheel
Pi：

```sh
pi install npm:@iflytekopensource/adapters
pi install npm:@iflytekopensource/memflywheel
```

Hermes：

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

OpenCode：

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

OpenClaw：

```sh
openclaw plugins install npm:@iflytekopensource/adapters
openclaw plugins install npm:@iflytekopensource/memflywheel
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
Expand All @@ -118,12 +118,11 @@ export MEMFLYWHEEL_EMBEDDING_MODEL="text-embedding-3-small"

## 安装包

| Package | 作用 |
| ------------------------------------------------------------------------------------------ | --------------------------------------------------------------- |
| [`@iflytekopensource/adapters`](https://www.npmjs.com/package/@iflytekopensource/adapters) | Pi、OpenCode、OpenClaw，以及 Hermes bridge 复用的宿主适配运行层 |
| [`@iflytekopensource/hermes`](https://www.npmjs.com/package/@iflytekopensource/hermes) | Hermes MemoryProvider 安装器和 skill 镜像 |
| Package | 作用 |
| ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------- |
| [`@iflytekopensource/memflywheel`](https://www.npmjs.com/package/@iflytekopensource/memflywheel) | Pi、Hermes、OpenCode 和 OpenClaw 集成，包含 Hermes MemoryProvider 安装器和 skill 镜像 |

内部 workspace 包按职责拆代码；普通用户只安装自己宿主需要的包。
内部 workspace 包按职责拆代码；四个宿主的用户都安装同一个公开包。

## 评测

Expand Down
14 changes: 7 additions & 7 deletions SUPPORT.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,13 +6,13 @@ https://github.com/iflytek/memflywheel/issues

Before filing an issue, please include:

| Field | Example |
| --------------- | ---------------------------------------------------------------------------------------------------------------------- |
| Package | `@memflywheel/core`, `@memflywheel/model`, `@memflywheel/sdk`, `@memflywheel/skills`, or `@iflytekopensource/adapters` |
| Runtime | Node.js version and operating system |
| Command | The exact command or API call that failed |
| Expected result | What you expected to happen |
| Actual result | What happened instead |
| Field | Example |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| Package | `@memflywheel/core`, `@memflywheel/embeddings`, `@memflywheel/sdk`, `@memflywheel/skills`, or `@iflytekopensource/memflywheel` |
| Runtime | Node.js version and operating system |
| Command | The exact command or API call that failed |
| Expected result | What you expected to happen |
| Actual result | What happened instead |

Do not include API keys, tokens, private memory files, or private filesystem
paths in public issues.
14 changes: 7 additions & 7 deletions docs/architecture.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,10 +5,10 @@ MemFlywheel is a file-backed long-term memory kernel. It has four moving parts
atomic writes, audit) that every write path shares.

The core (`@memflywheel/core`) is pure filesystem logic plus injected ports. It never owns
model transport, provider auth, or provider wire shapes. The two generative steps
(extraction, dream) reach the model only through injected function contracts; optional
model transport, provider auth, or provider wire shapes. The generative steps
(extraction, dream, and skill evolution) reach the model only through injected function contracts; optional
index-layer retrieval consumes a host-supplied embedding provider. Hosts wire those
contracts and the turn lifecycle through `@memflywheel/sdk` and `@iflytekopensource/adapters`.
contracts and the turn lifecycle through `@memflywheel/sdk` and `@iflytekopensource/memflywheel`.

## Memory root and layout

Expand Down Expand Up @@ -185,9 +185,9 @@ reusable skill route for future turns.

## Package boundaries

Only `@iflytekopensource/adapters` and `@iflytekopensource/hermes` are public npm packages.
The layers below remain private workspace packages; release builds bundle the
runtime pieces into the host-facing packages.
`@iflytekopensource/memflywheel` is the only public npm package. The layers below
remain private workspace packages; the release build bundles their runtime pieces,
all four host entrypoints, and the Hermes installer into that package.

```
@memflywheel/core filesystem only, no LLM, no host coupling
Expand All @@ -197,7 +197,7 @@ runtime pieces into the host-facing packages.
@memflywheel/sdk wires injection points + turn lifecycle
▲
│
@iflytekopensource/adapters per-host lifecycle mapping
@iflytekopensource/memflywheel host mappings + native model bindings + installers
```

See [`integrations.md`](integrations.md) for the SDK and host adapter surfaces.
Loading