MemFlywheel: Solving the 'Amnesia' of AI Agents with File-Native Memory

Today, GitHub Trending is dominated by Agent-driven automation. Tools like iOfficeAI/OfficeCLI and ai-job-search are proving that LLMs are finally taking "hands" to execute real business workflows.

But there is a critical missing piece in this "Brain + Hands" equation: Memory.

Most agents are stateless. Every time you run a task, it starts from scratch. For repetitive business processes, this is inefficient. MemFlywheel from the iFLYTEK Astron ecosystem addresses this by providing a file-native long-term memory layer for Agent Harnesses.

Why "File-Native"?

In enterprise and privacy-sensitive scenarios, storing agent memory in proprietary databases or cloud APIs is often a no-go. MemFlywheel keeps memories as Markdown files (MEMORY.md).

• Inspectable: You can read what the agent "remembered".
• Diffable: You can track how understanding evolved over time.
• Portable: No vendor lock-in.

How It Works: The Memory Flywheel

MemFlywheel integrates into existing Agent Harnesses (like Pi, Hermes, OpenCode, OpenClaw) via npm packages. It creates a continuous loop:

1. Pre-recall: Before execution, it injects relevant index cues from MEMORY.md into the context.
2. Progressive Read: It reads memory bodies and source traces to provide deep context.
3. Turn-end Extraction: After the task, it extracts durable memories.
4. Dream Consolidation: In idle time, it consolidates memories and repairs inconsistencies.
5. Skill Evolution: Repeated workflows are automatically distilled into reusable learned skills.

Agent Harness
   |
   |-- 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

Integration & Setup

MemFlywheel is designed to be non-intrusive. The host Harness retains control over models, auth, and tools, while MemFlywheel owns the memory loop.

Quick Start with OpenCode

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

Quick Start with Hermes

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

Optional: Embedding for Scalability

For small memory indexes, MemFlywheel works without embeddings. As your memory grows, you can enable semantic recall by setting an OpenAI-compatible endpoint:

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

Conclusion

As agents move from "chatbots" to "autonomous workers," memory becomes the differentiator between a one-off script and a learning system. MemFlywheel offers a lightweight, transparent, and file-native way to give your agents a "long-term memory," ensuring that every run makes the next one smarter.

👉 Check out the repo: iflytek/memflywheel