diff --git a/README.md b/README.md index f57959c..25bb2a3 100644 --- a/README.md +++ b/README.md @@ -146,6 +146,7 @@ evolve. See [`docs/evaluation.md`](docs/evaluation.md). | ------------------------------------------------------------------ | --------------------------------------------------------------------------------- | | [`docs/architecture.md`](docs/architecture.md) | Storage layout, recall, extraction, dream, skill loop, package boundaries | | [`docs/integrations.md`](docs/integrations.md) | Pi, Hermes, OpenCode, OpenClaw, embedding pre-recall, SDK hooks, adapter boundary | +| [`docs/comparison.md`](docs/comparison.md) | What changes vs host-native memory, runtime overhead, when to use which | | [`docs/evaluation.md`](docs/evaluation.md) | LoCoMo position and local regression checks | | [`docs/release.md`](docs/release.md) | Versioning, npm release channel, publish checklist | | [`CHANGELOG.md`](CHANGELOG.md) | Release notes for public npm package versions | diff --git a/README.zh.md b/README.zh.md index 76d9e48..76d2280 100644 --- a/README.zh.md +++ b/README.zh.md @@ -135,6 +135,7 @@ MemFlywheel 使用面向 LoCoMo 的回归检查，让长期记忆能力在召回 | ------------------------------------------------------------------ | ------------------------------------------------------------------------- | | [`docs/architecture.md`](docs/architecture.md) | 存储布局、召回、提取、dream、技能闭环、包边界 | | [`docs/integrations.md`](docs/integrations.md) | Pi、Hermes、OpenCode、OpenClaw、embedding 预召回、SDK hooks、adapter 边界 | +| [`docs/comparison.md`](docs/comparison.md) | 与宿主原生记忆的差异、运行时开销、选型建议 | | [`docs/evaluation.md`](docs/evaluation.md) | LoCoMo 定位和本地回归检查 | | [`docs/release.md`](docs/release.md) | 版本规范、npm 发布渠道、发布检查清单 | | [`CHANGELOG.md`](CHANGELOG.md) | 公开 npm 包版本变更记录 | diff --git a/docs/comparison.md b/docs/comparison.md new file mode 100644 index 0000000..7e7cb60 --- /dev/null +++ b/docs/comparison.md @@ -0,0 +1,84 @@ +# MemFlywheel vs Host-Native Memory + +MemFlywheel replaces or extends the memory implementation that ships with an +Agent Harness. This page explains what actually changes on each host, what the +memory flywheel adds over a native store, what it costs at runtime, and when +staying on native memory is the right call. + +Installation for every host lives in the [README Quick Start](../README.md#quick-start); +per-host wiring, verification tables, and troubleshooting live in +[`integrations.md`](integrations.md). This page only covers _whether_ and _why_. + +## What Changes Per Host + +| Host | Install path | Effect on native memory | +| -------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | +| Pi | `pi install npm:@iflytekopensource/adapters` | Additive: loads as a Pi extension; nothing on the host is disabled | +| Hermes | `memflywheel-hermes-install` + `memory.provider` config | Replacing: the installer disables Hermes' native memory toolset and moves existing `memories/MEMORY.md` aside | +| OpenClaw | `openclaw plugins install` + `plugins.slots.memory` config | Replacing: OpenClaw enables exactly one memory slot, so `memflywheel` takes the place of the default `memory-core` plugin | +| OpenCode | `opencode plugin @iflytekopensource/adapters --global` | Additive: loads as an OpenCode plugin; hooks provide recall, extraction, and skills | + +Switching back is symmetric: point the Hermes provider or the OpenClaw memory +slot back at the native implementation. The MemFlywheel store is plain Markdown +on disk, so nothing is lost or locked in either direction. + +## Capability Comparison + +Native memory implementations differ per host, but they are typically a single +store the main agent reads and writes directly. MemFlywheel splits memory into +a read side (recall) and a model-driven write side (extraction, dream, skill +evolution) that runs outside the main agent's turn. + +| Dimension | Typical host-native memory | MemFlywheel | +| ------------------ | ----------------------------------------------- | ----------------------------------------------------------------------------------------------- | +| Storage | Host-specific store, often a single memory file | File-native Markdown tree with typed directories (`identity/`, `preference/`, `workflow/`, ...) | +| Recall | Whole store or manual lookup | Progressive: index cues injected at prompt build, bodies read only when the agent decides to | +| Writing | Main agent edits memory in-turn | Turn-end extraction by a dedicated subagent, outside the main turn | +| Maintenance | Manual cleanup | Idle-time dream consolidation: dedupe, merge, compress, re-type | +| Repeated workflows | Stay as prose, re-derived every time | Evolve into learned skills; workflow memory compresses into a route pointing at the skill | +| Evidence | None | `## Sources` refs into cleaned session traces under `.memflywheel/sources/` | +| Auditability | Host-dependent | Append-only `.audit.log` for every write, delete, and archive | +| Privacy | Host-dependent | `` spans redacted on write; optional `refuseSecrets` gate refuses obvious secrets | +| Portability | Tied to the host | Same store layout on every host; `MEMFLYWHEEL_HOME` points any host at the same tree | +| Scaling | Whole store grows into the prompt | Index capped at 200 lines / 25 000 bytes, with optional embedding pre-recall above that | + +Not every host unlocks every row. Capability depends on what the host exposes — +see the capability levels table in [`integrations.md`](integrations.md#capability-levels): +recall-only needs prompt injection plus file read tools; the memory loop adds a +structured tool-call model and turn transcripts; the skill loop adds tool +trajectories and a learned-skill store. + +## Runtime Overhead + +MemFlywheel is not free. The flywheel spends model calls after the turn to make +the next turn cheaper and better grounded. + +| Cost | When | Size | +| -------------------- | ----------------------------------------- | ---------------------------------------------------------------------------------- | +| Prompt injection | Every prompt build | Memory rules plus at most 200 index lines / 25 000 bytes; small stores inject less | +| Turn-end extraction | After each turn with new messages | One subagent session over the new transcript window, via the host's model channel | +| Dream consolidation | Gated: ≥ 24 h elapsed or ≥ 5 sessions | One consolidation subagent pass over the cleaned store | +| Skill evolution | Only when repeated workflows are detected | Staged checkpoint writes, validated before publish | +| Embedding pre-recall | Optional, stores past ~200 index entries | Ordinary `/embeddings` calls against your OpenAI-compatible endpoint | +| Disk | Continuous | Markdown files, JSONL source traces, and index caches under the memory root | + +The write-side model calls go through the host's own model/auth channel where +the host provides one (Pi, Hermes); on OpenClaw and OpenCode they can use the +`MEMFLYWHEEL_LLM_*` environment variables instead. Recall itself never calls a +model — it is filesystem scan plus injection. + +## When To Use Which + +| Situation | Recommendation | +| ---------------------------------------------------------------------- | ---------------------------------------------------------------------------- | +| Long-lived assistant that should get better across sessions | MemFlywheel — extraction and dream compound over time | +| Same agent identity used across several harnesses | MemFlywheel — one portable store via `MEMFLYWHEEL_HOME` | +| Memories must be reviewable, diffable, or shipped through code review | MemFlywheel — plain Markdown plus audit log | +| Repeated multi-step workflows worth turning into reusable procedures | MemFlywheel — the skill loop exists for exactly this | +| One-shot batch jobs or stateless CI runs | Native (or no) memory — there is no next session to invest in | +| Extremely cost-sensitive turns where post-run model calls are unwanted | Native memory, or run MemFlywheel recall-only on a host without a model port | +| You rely on host-specific memory features MemFlywheel does not replace | Native memory — MemFlywheel only owns the memory and learning loop | + +A practical middle ground is to start recall-only: injection costs a bounded +prompt prefix and no extra model calls, and you can enable the write-side loops +once the memory store proves useful.