openclaw - 💡(How to fix) Fix [Feature]: Proposal: Integrate Purple Swan v3.0 Meta-Core as an OpenClaw Advanced Cognitive Module

Summary

Purple Swan is an enhanced fork of OpenClaw that fully preserves every message channel, CLI tool, and plugin system while adding a “Five-in-One Meta-Core” composed of hierarchical semantic memory (LanceDB), a self-evolution engine (EvoSkills), pre-action reflection (MIRROR), cross-session user/project profiling, and a self-correction loop. This proposal outlines a non-invasive plan to upstream these capabilities as optional packages and middleware, giving all OpenClaw users persistent memory, self-healing execution, and continuous learning without altering the existing architecture.

Problem to solve

Open Questions & Pending Issues

The following questions need to be resolved before or during the upstream integration:

1. Memory Namespace Isolation

   • How should memory entries be scoped? Per-user, per-channel, per-project, or a combination?
   • Should a memory created in a Telegram chat be recallable in a WhatsApp session by default?

2. Vector Store Lifecycle & Retention

   • What is a sensible default TTL (time-to-live) and maximum storage size for embedded LanceDB?
   • Should the memory store survive openclaw reinstall or major version upgrades?

3. Evolution Engine Governance

   • Who reviews and approves self-generated skills before they become actionable?
   • How to prevent skill explosion and infinite retry loops when the system fails to solve a task?

4. Pre-Action Reflection Threshold

   • Which actions qualify as “high-stakes” and trigger the MIRROR reflection? Is it a static list (e.g., file_delete, message_send) or configurable by the user?
   • Can reflection be bypassed with an explicit --force flag?

5. Profiling Privacy

   • USER.md and PROJECT.md may contain sensitive information. Should they be excluded from log files and error reports?
   • How to allow users to inspect and delete what the system has learned about them?

6. Upstream API Commitments

   • Which internal OpenClaw hooks/APIs do the new modules depend on? Are these stable enough to avoid breaking changes in minor releases?
   • Should the modules be released as bundled packages within the OpenClaw monorepo, or as standalone packages under the @openclaw scope on npm?

7. Testing & CI

   • What is the minimum test coverage required for merging the new modules?
   • How to handle flaky integration tests that depend on LLM output (self-correction loop, memory recall quality)?

8. Documentation & Onboarding

   • Will the features be documented in the existing OpenClaw docs site, or will they require a separate “Purple Swan” guide?
   • How should the openclaw onboard flow be updated to introduce these capabilities to new users without overwhelming them?

Proposed solution

Proposed Solutions

1. Memory Namespace Isolation

   • Introduce a three-level scoping model: user (global), project (repository-level), and session (temporary).
   • By default, memory is scoped to user, making it available across all channels and devices associated with the same OpenClaw identity.
   • Project-specific memories are stored in a local PROJECT.md and loaded only when the project context is active.
   • Users can override this behavior per command with a --scope flag or through configuration.

2. Vector Store Lifecycle & Retention

   • Set a default soft limit of 10,000 memory entries, with automatic eviction of the least recently used entries when the limit is exceeded.
   • Provide an optional per-entry TTL (e.g., 30 days for conversational facts, permanent for user preferences).
   • The memory store lives in the OpenClaw data directory and persists across reinstalls by default, with a command (openclaw memory purge) to reset it completely.
   • Major version upgrades include a migration script that preserves the vector index.

3. Evolution Engine Governance

   • All self-generated skills are initially saved in a “staging” state, marked as draft.
   • A skill is promoted to active only after it passes a sandboxed dry-run validation and, optionally, after the user approves it via openclaw skills review.
   • The evolution engine includes a circuit breaker: if a task fails more than 3 times, it stops attempting to generate new skills for that task and alerts the user.
   • Users can set a maximum number of automatically generated skills (default: 20).

4. Pre-Action Reflection Threshold

   • A static baseline list of high-stakes actions is provided: file_delete, file_overwrite, message_send, payment_execute, system_command.
   • Users can extend this list in config.yaml under a reflection.actions key, supporting wildcard patterns (e.g., shell:*).
   • Reflection can be bypassed with the --no-reflect flag, which requires explicit confirmation when used with high-stakes actions.
   • A “dry-run” mode is introduced that shows what reflection would have checked without actually blocking.

5. Profiling Privacy

   • USER.md and PROJECT.md are stored locally in the OpenClaw data directory and never transmitted to remote logging services.
   • By default, these files are excluded from error reports and debug bundles; inclusion requires an explicit opt-in.
   • A new command openclaw profile show displays everything the system has learned, and openclaw profile forget <key> lets users delete specific facts.
   • Encryption at rest (AES-256) is offered as an opt-in for the entire memory store, including profiles.

6. Upstream API Commitments

   • The new modules will depend only on public, documented OpenClaw extension points: the middleware pipeline, the plugin API, and the configuration system.
   • They will be submitted as packages inside the OpenClaw monorepo (packages/memory, packages/evolution, packages/reflect) to ensure they are versioned, tested, and released together with OpenClaw.
   • Any internal APIs they need will first be stabilized and exposed as public interfaces.
   • Standalone npm packages under @openclaw/ will be published later based on community demand, but the monorepo integration is the priority.

7. Testing & CI

   • Each module will include unit tests (covering pure logic, vector operations, and reflection rules) and integration tests (using a local LLM simulator to test the self-correction loop).
   • Flaky tests that depend on LLM output will be tagged as @llm-dependent and run only on-demand or in a scheduled pipeline, with deterministic fallback tests for CI.
   • Minimum coverage of 80% for all new code; self-evolution logic will have additional concurrency and isolation tests.
   • A golden-file approach will be used for memory recall quality: a set of known queries and expected top-3 results will be checked for stability.

8. Documentation & Onboarding

   • Documentation for the new capabilities will be integrated directly into the official OpenClaw docs site under a new “Cognitive Modules” section.
   • A dedicated “Purple Swan Guide” will be included as a sub-section for users who want to enable and configure all modules together.
   • The openclaw onboard flow will be updated with an optional step: “Enable advanced memory and self-evolution? [y/N]” with a brief explanation.
   • A short interactive tutorial (openclaw tutorial memory) will guide new users through their first memory recall and self-correction experience.

Alternatives considered

Design Alternatives Considered

For each open question, multiple approaches were evaluated. The chosen solution (detailed in the Proposed Solutions section) reflects a balance of simplicity, user control, and long-term maintainability. Below are the alternatives that were considered and why they were not selected.

1. Memory Namespace Isolation

   • Alternative A: Flat global memory only. All memories shared across all contexts. Rejected: Privacy risk and context pollution; a work chat memory could leak into a personal project.
   • Alternative B: Per-channel isolation (Telegram/WhatsApp/Discord silos). Rejected: Fragments user identity; defeats the purpose of a unified personal AI assistant.
   • Chosen: Three-level scoping (user/project/session). Balances continuity with contextual boundaries.

2. Vector Store Lifecycle & Retention

   • Alternative A: Infinite retention with manual cleanup. Rejected: Leads to unbounded disk growth and degraded recall quality over time.
   • Alternative B: Aggressive automatic pruning based solely on age. Rejected: Could delete rare but important user preferences that are infrequently recalled.
   • Chosen: Soft entry cap with LRU eviction plus optional per-entry TTL. Preserves important long-term facts while controlling storage.

3. Evolution Engine Governance

   • Alternative A: Fully automatic skill activation. Rejected: Too risky; a single bad self-generated skill could cause cascading failures.
   • Alternative B: Manual approval for every new skill. Rejected: Creates excessive user friction and undermines the value of self-evolution.
   • Chosen: Staged activation (draft → sandbox validation → optional user review). Provides safety with low-touch automation.

4. Pre-Action Reflection Threshold

   • Alternative A: Reflect on every action. Rejected: Would add unacceptable latency and token overhead to harmless operations like fetching weather.
   • Alternative B: LLM decides dynamically whether to reflect. Rejected: Non-deterministic; an attacker or prompt injection could convince the model to skip reflection.
   • Chosen: Static configurable list with wildcard support and force-override flag. Deterministic, transparent, and user-controlled.

5. Profiling Privacy

   • Alternative A: Profile stored encrypted at all times with mandatory passphrase. Rejected: Adds significant setup friction; not all users need military-grade protection for a personal AI.
   • Alternative B: No encryption, profile excluded from logs but freely readable on disk. Rejected: Insufficient for users storing API keys or sensitive project details in their profile.
   • Chosen: Local storage by default, excluded from telemetry, with opt-in AES-256 encryption. Right-sized security for most users.

6. Upstream API Commitments

   • Alternative A: Fork-only modules, never upstreamed. Rejected: Fragments the ecosystem and forces users to choose between OpenClaw and Purple Swan features.
   • Alternative B: Standalone npm packages only. Rejected: Makes version compatibility and integration testing significantly harder for OpenClaw maintainers.
   • Chosen: Monorepo packages first, standalone npm later. Ensures tight integration, shared CI, and consistent releases.

7. Testing & CI

   • Alternative A: Unit tests only, no LLM-dependent tests. Rejected: Would leave core behaviors (memory recall, self-correction) completely unvalidated in automated pipelines.
   • Alternative B: LLM-dependent tests in every CI run. Rejected: Too slow, expensive, and inherently flaky, blocking unrelated PRs.
   • Chosen: Hybrid approach — deterministic unit tests in CI, LLM-dependent tests in a scheduled pipeline with golden-file baselines.

8. Documentation & Onboarding

   • Alternative A: Fully optional, discoverable only via config file comments. Rejected: Most users would never find or enable the features.
   • Alternative B: Enabled by default with no onboarding. Rejected: Could confuse users expecting the classic OpenClaw behavior and generate unexpected memory storage.
   • Chosen: Opt-in prompt during openclaw onboard with dedicated tutorial. Smooths the learning curve while keeping the default experience unchanged.

Impact

Expected Impact

1. User Experience Transformation

• From tool to companion. OpenClaw users will move from issuing isolated commands to having an AI that remembers their preferences, context, and project history across sessions and devices.
• Reduced repetition. Common instructions (writing style, code conventions, server addresses) will no longer need to be restated in every prompt.
• Fewer catastrophic mistakes. Pre-action reflection will catch dangerous operations before they execute, saving users from accidental data loss, unintended messages, or misconfigured deployments.

2. Ecosystem & Extensibility

• Plug-and-play cognition. Plugin authors will be able to leverage the memory and reflection layers without reinventing them, leading to richer and smarter community plugins.
• Lower barrier to contribution. Self-evolution means the system can propose new skills automatically, reducing the pressure on maintainers and contributors to hand-code every edge case.
• Cross-channel coherence. A user who starts a workflow in Telegram can continue it in Discord or Slack with the same memory and personality, creating a genuinely omnichannel AI experience.

3. Maintainer & Project Health

• Reduced issue volume. Many user support requests stem from “the AI forgot what I said” or “it took a risky action without asking.” These capabilities directly address those root causes, likely reducing repetitive bug reports and feature requests.
• Gradual adoption path. Because the modules are optional and off by default, maintainers can merge them without destabilizing existing functionality or forcing users into new behaviors.
• Sustainable maintenance model. The Purple Swan author (luoxuejian000) will co-maintain the contributed modules, sharing the load and ensuring domain expertise stays within the project.

4. Competitive Differentiation

• First in class. No other open-source personal AI framework offers a built-in, production-tested combination of vector memory, self-evolution, and pre-action reflection as a unified, optional system. This positions OpenClaw as the most advanced self-hosted AI assistant available.
• Attracting advanced users. The feature set appeals to power users, developers, and teams who need a reliable long-term AI partner — expanding the community beyond early adopters.

5. Potential Negative Impact (Managed)

• Configuration complexity. More features could mean more configuration options. This is mitigated by sensible defaults and an opt-in design; the “classic” OpenClaw experience remains untouched.
• Storage footprint. Embedded LanceDB indices will consume additional disk space. The impact is controlled by configurable entry limits and TTLs, with typical footprints under 100 MB for most users.
• Learning curve for new users. The onboard prompt and interactive tutorial are designed to flatten this curve, introducing capabilities progressively.

6. Community & Culture

• A signal of openness to innovation. Accepting an upstream contribution from a fork demonstrates that OpenClaw values community-driven evolution. This can encourage more high-quality forks and experiments to eventually return to the main project.
• Stronger documentation culture. Integrating these modules will require clear, user-facing docs, setting a higher standard for how all OpenClaw features are documented.

Evidence/examples

No response

Additional information

No response