diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 854ab41..15e8b2d 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,22 +1,90 @@
# Contributing to MemFlywheel
-Thanks for helping improve MemFlywheel.
+Thanks for helping improve MemFlywheel. Contributions of code, tests,
+documentation, bug reports, integration feedback, and pull-request reviews are
+all welcome.
-This document covers project-specific guidelines. For broader community governance, contribution workflows, and code of conduct, see the [Iflytek Opensource Community](https://github.com/iflytek/community).
+This guide covers project-specific workflows. For broader community governance
+and contribution policy, see the
+[iFLYTEK Open Source Community](https://github.com/iflytek/community). All
+participation is covered by our [Code of Conduct](CODE_OF_CONDUCT.md).
-MemFlywheel is a file-native long-term memory layer for AI agents. It is a memory
-foundation component inside an Agent Harness, not a model, not an agent
-framework, and not a vector database.
+MemFlywheel is a file-native long-term memory layer for AI agents. It is a
+memory foundation component inside an Agent Harness—not a model, agent
+framework, or vector database.
-## Development
+## Choose a Way to Contribute
+
+- Browse [`good first issue`](https://github.com/iflytek/memflywheel/issues?q=is%3Aissue%20is%3Aopen%20label%3A%22good%20first%20issue%22)
+ and [`help wanted`](https://github.com/iflytek/memflywheel/issues?q=is%3Aissue%20is%3Aopen%20label%3A%22help%20wanted%22)
+ tasks.
+- [Report a reproducible bug](https://github.com/iflytek/memflywheel/issues/new?template=bug_report.md).
+- [Propose a feature](https://github.com/iflytek/memflywheel/issues/new?template=feature_request.md)
+ before investing in a large implementation.
+- Improve setup instructions, examples, tests, or host integrations.
+- Review an [open pull request](https://github.com/iflytek/memflywheel/pulls)
+ and leave focused, reproducible feedback.
+
+For questions and troubleshooting, follow [`SUPPORT.md`](SUPPORT.md). Report
+security vulnerabilities privately through the process in
+[`SECURITY.md`](SECURITY.md), not in a public issue.
+
+## Development Setup
+
+### Prerequisites
+
+- Git
+- Node.js 22.19 or later
+- pnpm 11.5.2 (the version declared in `package.json`)
+
+Fork the repository on GitHub, then clone your fork and install dependencies:
+
+```sh
+git clone https://github.com/YOUR-USERNAME/memflywheel.git
+cd memflywheel
+corepack enable
+corepack prepare pnpm@11.5.2 --activate
+pnpm install --frozen-lockfile
+```
+
+Add the upstream repository so your branch can stay current:
+
+```sh
+git remote add upstream https://github.com/iflytek/memflywheel.git
+git fetch upstream
+git switch -c feat/short-description upstream/main
+```
+
+Use a focused branch name such as `feat/...`, `fix/...`, `docs/...`, `test/...`,
+or `chore/...`.
+
+## Repository Map
+
+| Path | Purpose |
+| ---------------------- | ------------------------------------------------------------- |
+| `packages/core` | File-native storage, recall, extraction, consolidation |
+| `packages/embeddings` | Optional OpenAI-compatible embedding pre-recall |
+| `packages/sdk` | Model-driven learning loops and host-facing SDK surfaces |
+| `packages/skills` | Learned-skill representation and utilities |
+| `packages/memflywheel` | Public Pi, Hermes, OpenCode, and OpenClaw integration package |
+| `docs` | Architecture, integrations, evaluation, and release guides |
+| `examples` | Host integration examples |
+| `e2e` | Cross-host end-to-end coverage |
+
+## Development Commands
```sh
-pnpm install
-pnpm build
-pnpm test
-pnpm run ci
+pnpm build # Build all workspace packages
+pnpm test # Run package tests
+pnpm run lint # Run ESLint
+pnpm run format # Format supported files
+pnpm run ci # Run the complete local quality gate
```
+For a documentation-only pull request, `pnpm run format:check` is the minimum
+relevant check. Run `pnpm run ci` whenever code, package metadata, workflows, or
+executable examples change.
+
## Design Boundaries
Please keep changes inside the public MemFlywheel scope:
@@ -25,20 +93,67 @@ Please keep changes inside the public MemFlywheel scope:
| --------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| 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. |
+| Recall | Full-index recall only. Do not add embeddings, BM25, top-k, or vector search to the core recall contract. |
| 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_*`. |
+| Host role | Hosts continue to own models, credentials, tools, permissions, and sessions. |
+
+If a proposal would change one of these boundaries, open an issue first and
+explain the use case and trade-offs.
+
+## Make a Focused Change
+
+1. Reproduce the issue or describe the desired behavior.
+2. Add or update tests for behavior changes.
+3. Implement the smallest coherent change.
+4. Update public documentation when commands, configuration, or behavior change.
+5. Run the relevant checks and inspect the final diff.
+
+Keep commits focused and avoid unrelated formatting churn. Conventional commit
+subjects are preferred, for example:
+
+```text
+feat(core): preserve source traces during extraction
+fix(openclaw): wait for background memory writes
+
+docs: clarify Hermes installation
+```
+
+## Pull Request Checklist
+
+Before opening a pull request:
+
+- [ ] The branch is current with `upstream/main`.
+- [ ] Tests cover changed behavior.
+- [ ] `pnpm run ci` passes, or the PR explains why a narrower documentation-only
+ check is sufficient.
+- [ ] User-facing commands, examples, and documentation are updated.
+- [ ] Package metadata still points to `iflytek/memflywheel`.
+- [ ] No credentials, private memory content, private paths, old project names,
+ or AI-signature footers were added.
+- [ ] The change stays within the design boundaries above.
+- [ ] The PR links its issue with `Fixes #123` when applicable.
+
+When you open the PR, include a concise summary, validation evidence, and any
+special notes reviewers need. Respond to review comments with either a code
+change or a short explanation so the decision remains auditable.
+
+## Review Contributions
-## Pull Requests
+Reviewing pull requests is a valuable contribution. Check:
-Before opening a PR:
+- correctness and error paths;
+- privacy and credential handling;
+- compatibility across supported hosts;
+- tests and reproducible validation;
+- documentation for changed public behavior;
+- adherence to the file-native and host-native boundaries.
-1. Run `pnpm run ci`.
-2. Check that package metadata points to `iflytek/memflywheel`.
-3. Check that no secrets, private paths, old names, or AI-signature footers were added.
-4. Keep commits focused and avoid unrelated formatting churn.
+Prefer specific comments that explain impact and, where possible, suggest a
+verifiable next step.
## Public Hygiene
-Do not include credentials, private local paths, internal project names, or AI
-generation footers/trailers.
+Do not include credentials, private local paths, internal project names,
+private memory files, or AI-generation footers/trailers. Sanitize logs and
+examples before posting them publicly.
diff --git a/README.md b/README.md
index 5cae298..910c69b 100644
--- a/README.md
+++ b/README.md
@@ -5,8 +5,8 @@
- MemFlywheel
- Turn every Agent run into a smarter start for the next one!
+ Agent-native long-term memory that learns after every run
+ File-native, auditable, and integrated with Pi, Hermes, OpenCode, and OpenClaw.
@@ -25,26 +25,32 @@
-MemFlywheel adds a file-native memory flywheel to Agent Harnesses: recall before
-execution, extract after execution, and evolve repeated workflows into learned
-skills.
+MemFlywheel is an open-source, file-native long-term memory layer for AI agents.
+It helps an agent recall useful context before a task, extract durable knowledge
+after the task, consolidate memory while idle, and turn repeated workflows into
+reusable skills—without hiding the result in an opaque database.
-
-
- 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 one npm package. |
-
-
+> **Already using an agent harness?** Install one npm package, connect
+> MemFlywheel as the host's native memory plugin, and keep your existing models,
+> credentials, tools, permissions, and sessions.
+
+## Why MemFlywheel?
-## Why It Exists
+Most AI agents begin every run with limited context. MemFlywheel creates a
+continuous learning loop while keeping developers in control:
-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.
+| Capability | What it gives you |
+| ------------------------ | ------------------------------------------------------------------------------------------------------ |
+| **File-native memory** | Markdown memories, YAML metadata, source traces, and learned skills that are inspectable and diffable. |
+| **Progressive recall** | Lightweight index cues first, followed by relevant memory bodies, evidence, and skills. |
+| **Post-run learning** | Durable extraction at turn end plus dream consolidation and repair during idle time. |
+| **Reusable skills** | Repeated successful workflows can evolve into explicit skills the agent can inspect and reuse. |
+| **Harness-native setup** | One public npm package for Pi, Hermes, OpenCode, and OpenClaw. |
+| **Model-agnostic core** | The host retains model access and credentials; MemFlywheel owns only the memory-and-learning loop. |
+
+MemFlywheel is designed for teams that want persistent agent memory with an
+auditable storage model—not a new agent framework, model service, or vector
+database.
## How It Works
@@ -64,24 +70,42 @@ MemFlywheel
-  |
-  |
+ |
+ |
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. |
+ Skill flywheel
Repeated work evolves into reusable learned skills the agent can inspect and reuse. |
+## Supported Agent Harnesses
+
+| Host | Integration path |
+| ------------ | --------------------------------------------------------------- |
+| **Pi** | Native Pi package |
+| **Hermes** | MemoryProvider installer and skill mirror |
+| **OpenCode** | Global plugin |
+| **OpenClaw** | Memory-slot plugin with conversation and prompt-injection hooks |
+
+See the complete setup, verification commands, and troubleshooting guide in
+[`docs/integrations.md`](docs/integrations.md).
+
## Quick Start
-Pi:
+**Requirements:** Node.js 22.19 or later and a supported agent harness.
+
+
+Pi
```sh
pi install npm:@iflytekopensource/memflywheel
```
-Hermes:
+
+
+
+Hermes
```sh
npm install -g @iflytekopensource/memflywheel
@@ -89,14 +113,20 @@ memflywheel-hermes-install
hermes config set memory.provider memflywheel
```
-OpenCode:
+
+
+
+OpenCode
```sh
opencode plugin @iflytekopensource/memflywheel --global
opencode run --dir /path/to/project "your task"
```
-OpenClaw:
+
+
+
+OpenClaw
```sh
openclaw plugins install npm:@iflytekopensource/memflywheel
@@ -106,15 +136,18 @@ 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.
-Embedding pre-recall is optional. Without it, MemFlywheel still works and
-injects up to 200 generated `MEMORY.md` index lines directly. Once your memory
-index grows beyond that, start any OpenAI-compatible embeddings endpoint and
-export these variables before starting the host; pre-recall then turns on
-automatically and injects only the most relevant index entries.
+### Optional embedding pre-recall
+
+MemFlywheel works without an embedding service and can inject up to 200
+generated `MEMORY.md` index lines directly. For larger memory indexes, start any
+OpenAI-compatible embeddings endpoint and export these variables before starting
+the host. MemFlywheel then injects only the most relevant index entries.
```sh
export MEMFLYWHEEL_EMBEDDING_ENDPOINT="https://embedding-gateway.example.com/v1"
@@ -122,10 +155,7 @@ export MEMFLYWHEEL_EMBEDDING_API_KEY="..."
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 Package
+## Package
| Package | Role |
| ------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------- |
@@ -134,11 +164,17 @@ Host setup, embedding pre-recall, verification, and troubleshooting live in
Internal workspace packages keep the code split by responsibility; users install
the same public package for every supported host.
-## Evaluation
+## Architecture and Evaluation
+
+MemFlywheel keeps memory as Markdown with YAML frontmatter and treats
+`MEMORY.md` as a rebuildable index. The core stays independent of direct model
+calls; host-resolved model bindings run extraction and other write-side tasks.
+Read the full [architecture](docs/architecture.md) for storage and package
+boundaries.
-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`](docs/evaluation.md).
+LoCoMo-oriented regression checks keep long-term-memory behavior measurable as
+recall, extraction, consolidation, and learned-skill loops evolve. See the
+[evaluation guide](docs/evaluation.md).
## Documentation
@@ -148,17 +184,44 @@ evolve. See [`docs/evaluation.md`](docs/evaluation.md).
| [`docs/integrations.md`](docs/integrations.md) | Pi, Hermes, OpenCode, OpenClaw, embedding pre-recall, SDK hooks, adapter boundary |
| [`docs/evaluation.md`](docs/evaluation.md) | LoCoMo position and local regression checks |
| [`docs/release.md`](docs/release.md) | Versioning, npm release channel, publish checklist |
+| [Project website](https://iflytek.github.io/memflywheel/) | Search-friendly overview, quick start, and contribution paths |
| [`CHANGELOG.md`](CHANGELOG.md) | Release notes for public npm package versions |
| [`NOTICE`](NOTICE), [`THIRD_PARTY_LICENSES`](THIRD_PARTY_LICENSES) | Project notice and third-party license disclosure |
-## Open-Source Boundary
+## Contributing
+
+Developer collaboration is welcome—whether you want to improve a host
+integration, memory lifecycle behavior, documentation, tests, or developer
+experience.
+
+- Read the [contribution guide](CONTRIBUTING.md) to set up the workspace and
+ understand the project's design boundaries.
+- Browse [good first issues](https://github.com/iflytek/memflywheel/issues?q=is%3Aissue%20is%3Aopen%20label%3A%22good%20first%20issue%22)
+ or [help wanted issues](https://github.com/iflytek/memflywheel/issues?q=is%3Aissue%20is%3Aopen%20label%3A%22help%20wanted%22).
+- [Report a bug](https://github.com/iflytek/memflywheel/issues/new?template=bug_report.md),
+ [request a feature](https://github.com/iflytek/memflywheel/issues/new?template=feature_request.md),
+ or open a [general issue](https://github.com/iflytek/memflywheel/issues/new/choose).
+- Review an [open pull request](https://github.com/iflytek/memflywheel/pulls)
+ and share focused, reproducible feedback.
+
+Please run `pnpm run ci` before opening a pull request. All participation is
+covered by the [Code of Conduct](CODE_OF_CONDUCT.md).
+
+## Project Scope
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,
+file-native, model-agnostic, and host-first; it does not absorb the main agent,
model service, tool permissions, or skill execution into itself.
-## 💬 Community
+## Community and Support
+
+- Use [GitHub Issues](https://github.com/iflytek/memflywheel/issues) for public
+ questions, bug reports, and feature requests.
+- Read [`SUPPORT.md`](SUPPORT.md) before sharing logs or memory samples.
+- Join the Astron Open Source Community (WeCom Group) to discuss and collaborate:
+
+
-Join the Astron Open Source Community (WeCom Group) to discuss and collaborate:
+## License
-
+MemFlywheel is licensed under the [Apache License 2.0](LICENSE).
diff --git a/README.zh.md b/README.zh.md
index 5ee13eb..24f2c5a 100644
--- a/README.zh.md
+++ b/README.zh.md
@@ -137,15 +137,28 @@ MemFlywheel 使用面向 LoCoMo 的回归检查，让长期记忆能力在召回
| [`docs/integrations.md`](docs/integrations.md) | Pi、Hermes、OpenCode、OpenClaw、embedding 预召回、SDK hooks、adapter 边界 |
| [`docs/evaluation.md`](docs/evaluation.md) | LoCoMo 定位和本地回归检查 |
| [`docs/release.md`](docs/release.md) | 版本规范、npm 发布渠道、发布检查清单 |
+| [项目网站](https://iflytek.github.io/memflywheel/) | 面向搜索收录的项目介绍、快速开始和贡献入口 |
| [`CHANGELOG.md`](CHANGELOG.md) | 公开 npm 包版本变更记录 |
| [`NOTICE`](NOTICE)、[`THIRD_PARTY_LICENSES`](THIRD_PARTY_LICENSES) | 项目版权告知和三方 license 披露 |
+## 参与贡献
+
+欢迎通过代码、测试、文档、问题复现和 PR 审阅参与 MemFlywheel：
+
+- 阅读英文版 [`CONTRIBUTING.md`](CONTRIBUTING.md)，了解开发环境、仓库结构、设计边界与 PR 检查项；
+- 浏览 [`good first issue`](https://github.com/iflytek/memflywheel/issues?q=is%3Aissue%20is%3Aopen%20label%3A%22good%20first%20issue%22) 和 [`help wanted`](https://github.com/iflytek/memflywheel/issues?q=is%3Aissue%20is%3Aopen%20label%3A%22help%20wanted%22)；
+- [提交 Bug](https://github.com/iflytek/memflywheel/issues/new?template=bug_report.md)、[提出功能建议](https://github.com/iflytek/memflywheel/issues/new?template=feature_request.md)，或参与[开放 PR](https://github.com/iflytek/memflywheel/pulls)审阅。
+
+提交 PR 前请运行 `pnpm run ci`。所有社区参与均遵循 [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md)。
+
## 开源边界
MemFlywheel 的目标是成为 Agent Harness 里的长期记忆和技能学习基础组件。它保持文件原生、模型无关、宿主优先，不把主 Agent、模型服务、工具权限或技能执行吞进自己内部。
## 💬 社区交流
+如有公开问题、Bug 或功能建议，请优先使用 [GitHub Issues](https://github.com/iflytek/memflywheel/issues)，并在分享日志或记忆样例前阅读 [`SUPPORT.md`](SUPPORT.md)。
+
欢迎加入 Astron 开源交流群（企业微信），与我们交流与合作：
diff --git a/docs/_config.yml b/docs/_config.yml
new file mode 100644
index 0000000..df317c2
--- /dev/null
+++ b/docs/_config.yml
@@ -0,0 +1,11 @@
+title: MemFlywheel — File-Native Long-Term Memory for AI Agents
+description: Open-source agent memory with auditable Markdown storage, progressive recall, post-run learning, and integrations for Pi, Hermes, OpenCode, and OpenClaw.
+theme: jekyll-theme-cayman
+lang: en-US
+url: https://iflytek.github.io
+baseurl: /memflywheel
+repository: iflytek/memflywheel
+github:
+ is_project_page: true
+ repository_url: https://github.com/iflytek/memflywheel
+ owner_url: https://github.com/iflytek
diff --git a/docs/index.md b/docs/index.md
new file mode 100644
index 0000000..71efab3
--- /dev/null
+++ b/docs/index.md
@@ -0,0 +1,94 @@
+# MemFlywheel
+
+MemFlywheel is an open-source, file-native long-term memory layer for AI agents.
+It helps agents recall relevant context before a task, extract durable knowledge
+after each run, consolidate memory while idle, and turn repeated workflows into
+reusable learned skills.
+
+
+ View on GitHub
+ ·
+ Install from npm
+ ·
+ Integration guide
+ ·
+ 简体中文
+
+
+
+
+## Agent memory that stays inspectable
+
+MemFlywheel stores Markdown memories, YAML metadata, source traces, and learned
+skills as ordinary files. Developers can inspect, diff, review, back up, and
+version the agent's long-term knowledge instead of placing it behind an opaque
+memory service.
+
+| Capability | What it gives you |
+| ------------------------- | ---------------------------------------------------------------------------- |
+| File-native memory | Auditable Markdown memories and source traces |
+| Progressive recall | Index cues followed by relevant memory bodies, evidence, and skills |
+| Post-run learning | Turn-end extraction plus idle-time consolidation and repair |
+| Learned skills | Repeated workflows can become explicit, reusable skills |
+| Agent-harness integration | One npm package supports Pi, Hermes, OpenCode, and OpenClaw |
+| Model-agnostic core | The host retains model access, credentials, tools, permissions, and sessions |
+
+## Quick start
+
+Choose your agent harness:
+
+### Pi
+
+```sh
+pi install npm:@iflytekopensource/memflywheel
+```
+
+### Hermes
+
+```sh
+npm install -g @iflytekopensource/memflywheel
+memflywheel-hermes-install
+hermes config set memory.provider memflywheel
+```
+
+### OpenCode
+
+```sh
+opencode plugin @iflytekopensource/memflywheel --global
+```
+
+### OpenClaw
+
+```sh
+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
+openclaw gateway run --force
+```
+
+Node.js 22.19 or later is required. Continue with the
+[full integration and troubleshooting guide](integrations.html).
+
+## Learn more
+
+- [Architecture](architecture.html): storage, recall, extraction, consolidation, and
+ package boundaries
+- [Integrations](integrations.html): Pi, Hermes, OpenCode, OpenClaw, and optional
+ embedding pre-recall
+- [Evaluation](evaluation.html): LoCoMo-oriented long-term-memory regression checks
+- [Releases](release.html): versioning and npm release workflow
+
+## Contribute
+
+Contributions to host integrations, memory behavior, tests, documentation, and
+developer experience are welcome.
+
+- Read the [contribution guide](https://github.com/iflytek/memflywheel/blob/main/CONTRIBUTING.md).
+- Browse [good first issues](https://github.com/iflytek/memflywheel/issues?q=is%3Aissue%20is%3Aopen%20label%3A%22good%20first%20issue%22)
+ and [help wanted issues](https://github.com/iflytek/memflywheel/issues?q=is%3Aissue%20is%3Aopen%20label%3A%22help%20wanted%22).
+- [Report a bug or propose a feature](https://github.com/iflytek/memflywheel/issues/new/choose).
+- Review an [open pull request](https://github.com/iflytek/memflywheel/pulls).
+
+MemFlywheel is open source under the
+[Apache License 2.0](https://github.com/iflytek/memflywheel/blob/main/LICENSE).