feat(integrations/OpenClaw): research on OpenClaw memory and how to integrate PowerContext as a multi-session Memory Provider

[XnLemon]

Background

This issue investigates OpenClaw's memory mechanism and evaluates the feasibility and implementation path for integrating PowerContext as a standard OpenClaw Memory Provider plugin.

OpenClaw memory consists of built-in memory, external memory plugins, runtime tools, session transcripts, and lifecycle hooks. PowerContext is best positioned as an external long-term memory and project-context backend. It should not replace OpenClaw's session store, routing, or transcript authorization.

1. OpenClaw Memory Mechanism

1.1 Memory layers and responsibilities

OpenClaw memory includes:

• Built-in memory: MEMORY.md, USER.md, and daily memory files managed by the workspace. These are suitable for stable facts, preferences, and Agent rules.
• External Memory Provider: A plugin selected through OpenClaw's memory slot. It provides semantic search, context preparation, memory writes, indexing, and consolidation.
• Runtime tool calls: Memory plugins may expose search, get, remember, revise, and retire tools.
• Session transcript recall: OpenClaw owns session transcripts. Cross-session recall is subject to runtime authorization and is limited to eligible same-agent private conversations.
• Lifecycle hooks: Memory plugins may participate in prompt building, turn capture, pre-compaction, flushing, and session-end processing.
• Active Memory: Bounded recall based on the current user turn and recent context.
• Promotion / dreaming: Source records may be consolidated into durable Memory, Experience, or Skill objects.

MEMORY.md / USER.md
    = curated, human-editable facts

memory provider
    = searchable long-term and project context

session transcript recall
    = historical OpenClaw sessions
    = only available after runtime authorization

PowerContext
    = external source, memory, and bounded context layer

Isolation must not be implemented only by comparing string scopes:

• agentId is the main agent/workspace isolation boundary.
• sessionKey identifies a conversation but does not by itself grant access.
• Private cross-session recall requires the same agent, a private destination, and trusted runtime authorization.
• Group, channel, and cross-agent transcripts must not become visible because they share a string prefix or project scope.

1.2 Core Provider interfaces

OpenClaw does not use a single Hermes-style MemoryProvider class. Its provider contract is composed from plugin capabilities and lifecycle hooks.

A standard PowerContext provider should cover:

• Plugin manifest and kind: "memory".
• registerMemoryCapability.
• promptBuilder for bounded prompt context.
• getMemorySearchManager for semantic search.
• authorizeSearchHits for caller-visible authorization.
• flushPlanResolver for compaction and lifecycle flushes.
• Tool registration for explicit memory operations.
• before_prompt_build or equivalent prefetch processing.
• Turn capture and session-end synchronization.
• Cleanup and shutdown of clients and search managers.

Responsibilities:

• Prompt builders inject only bounded, high-confidence, explainable context.
• Prefetch uses the current turn and verified scope; it must not inject complete history.
• Tools return source, citation, timestamp, relevance, and revision metadata.
• Turn synchronization captures filtered Source records instead of blindly copying transcripts.
• Protected transcript recall must consume trusted runtime context such as conversationRecall; the model must not choose the agent, session, or corpus.

2. PowerContext's Position in OpenClaw

2.1 Overall positioning

PowerContext should serve as OpenClaw's external long-term memory, project-context, and bounded retrieval layer, integrated through the OpenClaw Memory Provider capability.

PowerContext should handle:

• Long-term semantic memory storage and retrieval.
• Agent- and project-scoped context.
• Source capture and memory consolidation.
• Memory search, write, revision, retirement, and synchronization.
• Important information preservation before compaction.
• Review-gated Experience and Skill generation.
• Cited memory tools.

OpenClaw should remain responsible for:

• Agent orchestration.
• System and developer prompt policy.
• Tool scheduling.
• Canonical session transcript storage.
• Agent, session, channel, and privacy authorization.
• Protected cross-session transcript recall.

PowerContext must not replace OpenClaw's session store or reconstruct transcript authorization from scope_id.

2.2 Relationship with OpenClaw built-in memory

The recommended approach is additive:

• OpenClaw built-in memory remains responsible for stable, human-editable information.
• PowerContext stores larger-scale, searchable, continuously accumulated context.
• OpenClaw injects only a small amount of general long-term context.
• Task-specific or lengthy context is retrieved through bounded prefetch or explicit tools.
• Built-in memory writes may be mirrored only when OpenClaw provides a canonical write event.
• Otherwise, use explicit import/export rather than creating an uncoordinated dual-write path.
• PreparedContext is ephemeral and must not automatically become a new durable fact.

A single canonical owner should be defined for each fact. Conflict, supersession, revision, retirement, and deletion semantics must be explicit.

2.3 PowerContext responsibilities

• Store long-term memories produced by OpenClaw users, agents, sessions, and projects.
• Retrieve relevant memories using the current user input and verified session context.
• Organize and semantically compress historical context.
• Support memory write, search, get, revise, retire, and change synchronization.
• Capture bounded Source records with provenance.
• Preserve important facts before context compression.
• Expose cited memory tools.
• Maintain deterministic and idempotent source identifiers.
• Keep Experience and Skill promotion behind PowerContext review gates.
• Return observable provider failures instead of silently treating failure as an empty result.

Recommended scope mapping:

openclaw:agent:<agentId>
    = agent-scoped long-term memory

openclaw:agent:<agentId>:project:<projectKey>
    = project-scoped memory

conversation identity
    = opaque correlation and idempotency identifier
    = not an authorization token

A user scope should only be created from an authoritative authenticated profile. Do not infer identity from display names, session keys, or routing metadata.

2.4 Recommended data flow

1. OpenClaw admits a session and resolves trusted agent, project, session, channel, and privacy facts.
2. The Provider initializes the PowerContext client and creates an internal scope_id.
3. The Provider retrieves a small amount of general long-term context through a bounded prompt path.
4. For each user turn, the Provider calls /v1/context/prepare or /v1/memory/search with the current intent and verified scope.
5. The Agent uses cited PowerContext tools for more specific historical information.
6. After the turn, the Provider captures a filtered Source with a deterministic source_id.
7. At session end, the Provider triggers asynchronous extraction, organization, flush, and synchronization.
8. Before compaction, the Provider preserves important facts, preferences, task state, and unfinished work.
9. Protected cross-private-session recall uses only trusted OpenClaw conversationRecall context.

3. Implementation Plan: PowerContext as a Standard OpenClaw Memory Provider Plugin

OpenClaw already has a memory-powermem plugin with useful HTTP/CLI integration, automatic recall, automatic capture, and multi-agent support.

It is a useful prototype, but it does not yet fully implement the OpenClaw memory capability boundary:

• It does not register registerMemoryCapability.
• It does not implement authorizeSearchHits.
• Its hook-only recall path cannot enter the Active Memory protected transcript path.
• Its plugin-owned identity files are not equivalent to OpenClaw's authoritative identity.
• Its local SQLite fallback needs an explicit canonical-storage or cache decision.
• Its forget behavior must be aligned with PowerContext revision and retirement semantics.

The recommended approach is to reuse its transport experience and evolve it into a capability-compliant PowerContext provider.

3.1 Plugin structure

Add an independent external plugin package:

memory-powercontext/
├── openclaw.plugin.json
├── package.json
├── index.ts
├── src/
│   ├── provider.ts
│   ├── client.ts
│   ├── config.ts
│   ├── scope.ts
│   ├── lifecycle.ts
│   ├── authorization.ts
│   ├── tools.ts
│   └── types.ts
└── README.md

Responsibilities:

• openclaw.plugin.json: plugin identity, kind: "memory", configuration, and capabilities.
• provider.ts: OpenClaw Memory Provider implementation.
• client.ts: PowerContext HTTP API client.
• config.ts: configuration, validation, and secret references.
• scope.ts: verified OpenClaw identity to PowerContext scope mapping.
• authorization.ts: session, agent, channel, and transcript visibility checks.
• lifecycle.ts: prompt preparation, capture, flush, compaction, and session-end processing.
• tools.ts: cited memory tools.
• README.md: installation, configuration, usage, and troubleshooting.

3.2 Mapping Provider capabilities to PowerContext APIs

OpenClaw capability	PowerContext API / mechanism
General context retrieval	/v1/context/prepare
Memory search	/v1/memory/search
Memory writing	/v1/memory/remember
Entry retrieval	/v1/memory/entries/get
Entry revision	/v1/memory/entries/revise
Entry retirement	/v1/memory/entries/retire
Session context preparation	/v1/context/prepare
Session flush	/v1/memory/flush
Change synchronization	/v1/memory/changes
Source capture	/v1/sources/content
Protected transcript recall	Requires a generic OpenClaw authorization seam
Prompt injection	promptBuilder / before_prompt_build
Search-hit authorization	Provider runtime plus trusted conversationRecall

Use the following distinction:

• remember: explicit durable memory write.
• sources/content: bounded evidence capture pending consolidation.
• context/prepare: ephemeral, query-specific bounded context.
• flush: Source-to-Memory consolidation.
• changes: incremental synchronization using a cursor.

3.3 Configuration design

The Provider configuration should include:

• PowerContext service URL.
• Authentication method and credentials.
• Agent, project, user, and opaque conversation identifiers.
• Scope mapping mode and shared-project policy.
• Retrieval count and similarity threshold.
• Maximum prompt injection bytes or tokens.
• General memory injection toggle.
• Per-turn prefetch toggle.
• Agent memory tools toggle.
• Automatic Source capture toggle.
• Session-end and pre-compaction flush toggles.
• Network timeout, retry count, and fallback behavior.
• Citation, provenance, and observability settings.
• Protected transcript recall support status.

Example:

{
  plugins: {
    slots: {
      memory: "memory-powercontext"
    },
    entries: {
      "memory-powercontext": {
        enabled: true,
        config: {
          endpoint: "https://powercontext.example",
          tokenEnv: "POWERCONTEXT_TOKEN",
          projectScopeMode: "explicit",
          autoRecall: true,
          autoCapture: true,
          prepareMaxBytes: 8000,
          searchTimeoutMs: 1200,
          flushTimeoutMs: 2000
        }
      }
    }
  }
}

Credentials must come from environment variables or a secret store and must never be committed or logged.

Full raw sessionKey must not be exposed as an authorization parameter. Cross-agent and shared-project memory must be disabled by default. Provider configuration and metadata should be process-stable; do not poll them on every request. Provider timeouts must fit within OpenClaw hook budgets. PowerContext failures must not block the main response.

3.4 Provider lifecycle implementation

Initialization

• Validate configuration and secret references.
• Create the PowerContext client.
• Use local availability checks without requiring a network health probe.
• Resolve the authoritative agentId.
• Resolve a verified project key when enabled.
• Create bounded timeout, retry, and observability policies.

System prompt injection

• Retrieve only a small set of stable long-term memories.
• Enforce a hard byte/token limit.
• Mark external context as untrusted and preserve source/citation metadata.
• Do not allow memory content to override system or developer instructions.
• Do not inject complete historical transcripts.
• Continue the main turn and record degraded state when the provider is unavailable.

Per-turn prefetch

• Call /v1/context/prepare or /v1/memory/search using the current intent and verified scope.
• Execute at most one bounded prefetch for an eligible turn.
• Cache results only for the current turn.
• Include source, timestamp, relevance, and citation.
• Never broaden project scope to agent or cross-agent scope implicitly.
• Do not use prefetch as a substitute for protected transcript authorization.

Agent tools

The Provider may expose:

• powercontext_search_memory
• powercontext_get_memory
• powercontext_remember
• powercontext_revise_memory
• powercontext_retire_memory

Tool results should include entry ID, source, citation, timestamp, relevance, scope, and revision.

Model-authored parameters must not expand the authorized corpus. Retirement should require an explicit entry identity and expected revision where applicable. A high-score search hit must not be deleted automatically.

Turn synchronization and session end

• Capture a bounded, filtered Source asynchronously.
• Use deterministic, idempotent Source IDs.
• Preserve agent, project, session, channel, privacy, timestamp, and provenance metadata.
• Do not persist complete raw conversations without filtering.
• Use /v1/sources/content for capture and /v1/memory/flush for consolidation.
• Use /v1/memory/changes for incremental synchronization.
• Trigger extraction and persistence asynchronously at session end.
• Make provider failures observable and non-blocking.

Pre-compression processing

• Use OpenClaw's memory flush lifecycle before compaction.
• Preserve important facts, preferences, task state, and unfinished work.
• Store structured Source records rather than complete raw conversations.
• Deduplicate and filter sensitive information.
• Keep Experience and Skill promotion behind PowerContext review gates.
• Do not inject pending candidates as approved facts.
• Verify availability after compression and restart.

Protected multi-session recall

PowerContext must not implement transcript authorization by comparing scope_id alone.

If PowerContext indexes OpenClaw transcripts:

• OpenClaw must provide a generic provider authorization contract.
• The runtime must provide trusted conversationRecall.
• The Provider must validate same-agent, private-conversation, visibility, reset, and lifecycle state.
• Authorization must remain valid after awaited network calls.
• Model-provided agent IDs, session IDs, and corpus values must not broaden access.
• Unsupported providers must return an explicit unsupported result.
• Tests must cover cross-agent, group/channel, stale-session, restart, reset, and replay cases.

Failure handling and verification

The provider must ensure:

• PowerContext timeout or 503 does not block the main response.
• Provider failure is distinguishable from an empty result.
• No unbounded retries or unauthorized fallback corpus.
• Duplicate Source capture is idempotent.
• Revision conflicts are explicit and recoverable.
• Prompt injection stays within the hard limit.
• Degraded behavior is observable.
• Tests cover Gateway turns, one-shot CLI, sandboxed sessions, restart, compaction, private multi-session recall, group/channel isolation, and cross-agent denial.

References

OpenClaw official documentation

• Memory
• Memory architecture
• Memory search
• Active memory
• Session
• Session search
• Multi-agent routing
• Compaction
• Memory configuration
• Memory Core plugin
• Memory LanceDB plugin
• OpenClaw plugin development

OpenClaw source references

• src/plugins/registry-contribution-types.ts
• src/plugins/memory-state.ts
• src/agents/conversation-recall.types.ts
• extensions/memory-core/index.ts
• extensions/memory-core/src/tools.ts
• extensions/active-memory/index.ts
• docs/concepts/memory-architecture.md

PowerContext references

• PowerContext repository
• PowerContext OpenAPI
• PowerContext interfaces
• PowerContext memory layer design
• PowerContext install and run
• PowerContext Codex integration
• Existing OpenClaw memory-powermem plugin
• Existing OpenClaw integration guide

Expected outcomes

• Document the mapping between OpenClaw memory capabilities and PowerContext APIs.
• Clarify PowerContext's responsibilities and data flow within OpenClaw.
• Align the integration with OpenClaw's active memory, session isolation, provider slot, and protected transcript recall model.
• Produce an actionable design for a standard OpenClaw Memory Provider plugin.
• Define scope mapping, lifecycle hooks, failure behavior, security boundaries, and multi-session acceptance criteria.
• Provide a foundation for implementation, testing, and documentation.

[XnLemon]

Follow-up:

Why TypeScript?

TypeScript is recommended for the OpenClaw integration layer because OpenClaw's core runtime and official plugins are implemented as TypeScript ESM modules. The OpenClaw Plugin SDK exposes typed contracts for plugin manifests, memory capabilities, runtime context, tool schemas, lifecycle hooks, session identity, and search authorization.

Using TypeScript provides:

• Compile-time validation against OpenClaw Plugin SDK interfaces.
• Safer handling of agent, session, project, and privacy-scope data.
• Typed integration with MemoryPluginCapability and MemoryPluginRuntime.
• Type-safe tool schemas and runtime parameters.
• Better compatibility with OpenClaw's existing build, test, lint, and packaging workflows.
• Easier maintenance when OpenClaw SDK contracts evolve.
• Consistency with the existing memory-core, memory-lancedb, and other official plugins.

The TypeScript code should be an OpenClaw-side adapter:

OpenClaw TypeScript Memory Provider
    |
    | HTTP API
    v
PowerContext service

PowerContext itself does not need to be rewritten in TypeScript. Its existing implementation can remain unchanged and communicate with the OpenClaw adapter through APIs such as:

• /v1/context/prepare
• /v1/memory/search
• /v1/memory/remember
• /v1/sources/content
• /v1/memory/flush

TypeScript is therefore a requirement and recommendation for the OpenClaw plugin boundary, not for the PowerContext backend. At publish time, the TypeScript plugin is compiled to JavaScript and OpenClaw executes the built JavaScript entry point.