MemFlywheel

MemFlywheel
Turn every Agent run into a smarter start for the next one!

English | 简体中文

MemFlywheel adds a file-native memory flywheel to Agent Harnesses: recall before execution, extract after execution, and evolve repeated workflows into learned skills.

File-native Markdown memories, source traces, and learned skills stay inspectable and diffable.	Progressive recall Pre-recall plus layered reads from index cues to evidence.
Post-run learning Turn-end extraction and dream consolidation keep memory moving.	Harness-native Pi, Hermes, OpenCode, and OpenClaw are supported through npm packages.

Why It Exists

Give your Agent a memory flywheel: recall before it acts, learn after it runs, and understand you better each time. The host Agent Harness owns lifecycle, model access, auth, and tools; MemFlywheel owns the memory and learning loop.

How It Works

Agent Harness
   |
   |  lifecycle / model / auth / tools
   v
MemFlywheel
   |
   |-- pre-recall       -> MEMORY.md index cues
   |-- progressive read -> memory bodies -> source traces -> learned skills
   |-- turn-end         -> durable memory extraction
   |-- idle             -> dream consolidation and repair
   `-- repeated work    -> reusable learned skills

Memory lifecycle Recall, extract, consolidate, and keep evidence close to the file-native store.	Skill flywheel Repeated work evolves into reusable learned skills the Agent can inspect and reuse.

Quick Start

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 "your task"

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 installs into each host as a native memory plugin. The host keeps owning models, tools, permissions, and sessions; MemFlywheel adds recall, turn-end extraction, dream consolidation, and learned skills.

Source checkout, verification, and debugging paths live in docs/integrations.md.

Install Packages

Package	Role
@iflytekopensource/adapters	Pi, OpenCode, OpenClaw, and the shared host-adapter runtime used by Hermes
@iflytekopensource/hermes	Hermes MemoryProvider installer and skill mirror

Internal workspace packages keep the code split by responsibility; users install only the host package they need.

Evaluation

MemFlywheel uses LoCoMo-oriented regression checks to keep long-term-memory behavior measurable while the recall, extraction, and learned-skill loops evolve. See docs/evaluation.md.

Documentation

Document	Content
docs/architecture.md	Storage layout, recall, extraction, dream, skill loop, package boundaries
docs/integrations.md	Pi, Hermes, OpenCode, and OpenClaw install, SDK hooks, adapter boundary
docs/evaluation.md	LoCoMo position and local regression checks
docs/release.md	Versioning, npm release channel, publish checklist
CHANGELOG.md	Release notes for public npm package versions
NOTICE, THIRD_PARTY_LICENSES	Project notice and third-party license disclosure

Open-Source Boundary

MemFlywheel is a foundation component inside an Agent Harness. It stays file-native, model-agnostic, and host-first; it does not absorb the main Agent, model service, tool permissions, or skill execution into itself.