OPENCLAW × HY-MEMORY INTEGRATION

Remember once,
accompany everywhere

Hy-Memory is an OpenClaw shared memory plugin based on Tencent Hunyuan's high-dimensional cognitive memory evolution framework. It structures and consolidates a user's long-term preferences, facts, personas, and intents into an evolvable memory core. Multiple agents can instantly query this centralized memory, resolving the amnesic limits of single-session histories.

GATEWAY STACK LOG
$ initialization pipeline running...
Hy-Memory Cyberpunk Core Image
STATUS: NEURAL CORE SYNCED CHRONOS ENGINE L6
SYS_TIME: 00:00:00 CURSOR: X=0000 Y=0000
VDB_STATUS: Chroma CONNECTED ACCURACY: 85.20% (LongMemEval)
HY-MEMORY EVOLUTIONARY CORE

NOT JUST CHAT HISTORY. A 6-LAYER COGNITIVE STRUCTURE.

Standard chat history merely appends text linearly, generating clutter and fading away over time. Hy-Memory runs an asynchronous System 2 engine that filters, merges, and crystallizes raw data into a structured 6-layer memory kernel.

CLICK LAYERS TO HIGHLIGHT CORRESPONDING FIELD
L4-L6: Mind & Intent
L3: Identity Profile
L2: Atomic Facts
L1: Raw Traces
HY-MEMORY KERNEL ARCHITECTURE
L1 LAYER

Raw Traces

Retains the original dialogues, actions, and raw context blocks. Serves as the primary data feed for downstream crystallization and hierarchy tagging.

L2 LAYER

Atomic Facts

Distills chaotic conversation chains into structured fact elements (subject-relation-object triplets) supporting semantic deduplication and logical merging.

L3 LAYER

Identity Profile

Models a stable configuration of a user's long-term preferences, personalities, roles, and profile traits. Easily shared across multi-agent workspaces.

L4-L6 LAYER

Mind & Intent

Deeply extracts long-range summaries, mental frameworks, and prospective intent structures, facilitating complex temporal reasoning and task planning.

ARCHITECTURAL SHIFT: LINEAR SESSION VS STRUCTURED COGNITION

OpenClaw Native Memory SESSION LIMIT

Linear text retention restricted to the active chat session. Spawning a new thread results in complete context loss, preventing long-term knowledge accumulation.

UPGRADE
Hy-Memory Engine UNLIMITED CORE

Centralized Python subprocess manages vector stores. Auto-recalls relevant memories before generation and asynchronously captures/distills facts after chat runs.

BENCHMARK TESTING STATUS

85.20% — LongMemEval Top Score in Category

On standard benchmarks (LongMemEval and PersonaMem), Hy-Memory leads competitors like mem0 and Graphiti by scoring highest in query accuracy and profile evolution tracing.

85.20%
LongMemEval Score
Ranked first among active memory engines (6 task types)
76.91%
PersonaMem Score
Leading accuracy in profile alignment (7 task types)
13 / 13
Categories Won
Outperformed all rivals in every single benchmark subset
8×
Write Speedup
8 times reduction in API process latency during ingestion

LongMemEval Overall Performance

Benchmark: 500 test cases
mem0
47.00%
Graphiti
68.32%
Hy-Memory
85.20%

* Standard subsets evaluate single-session facts, temporal order deduction, context updates, and multi-session facts.

End-to-End Write Latency Comparison (sec / 1k tokens)

Lower is faster (8x Speedup)
Graphiti
97.8s
mem0
15.6s
Cloud Memory API
5.36s
Hy-Memory
12.3s

While raw latency for simple database lookups like mem0 is low, their accuracy is severely compromised. Hy-Memory achieves the ideal trade-off by reducing API overhead to 12.3s/k tokens (1/8th of Graphiti) while maintaining top-tier benchmark scores.

DEPLOYMENT & INTEGRATION

Quick OpenClaw Setup

Follow these commands to deploy the plugin and configure model connections.

Confirm your environment has the following parameters resolved:

  • OpenClaw CLI Environment Make sure the openclaw CLI is globally executable on your machine.
  • Python Environment (>= 3.8) Required to bootstrap the local memory server daemon as a subprocess.
  • LLM Provider Configuration An active API Key pointing to an OpenAI-compatible endpoint. Recommended: Hunyuan 3.0 Preview.
  • Embedding Provider Configuration For semantic representations. Default recommendations use BAAI/bge-m3 hosted by SiliconFlow.

Install the plugin via the OpenClaw marketplace. Uninstall older builds to prevent workspace conflicts:

BASH TERMINAL Copied to clipboard! 
# Remove older package instances if present
openclaw plugins uninstall openclaw-hy-memory

# Force pull clean plugin release
openclaw plugins install openclaw-hy-memory --dangerously-force-unsafe-install
Why is the --dangerously-force-unsafe-install flag required?
Hy-Memory coordinates memory databases in the background via a sidecar Python process. To maintain system security boundaries, OpenClaw disables arbitrary execution of external processes by default, requiring this explicit bypass flag.

Initialize parameters using the guided interactive wizard to configure model connectivity:

BASH TERMINAL Copied to clipboard! 
openclaw hy-memory init
WIZARD ADVANTAGES
Follow the prompts to enter API Keys and URLs. The launcher will automatically test model connectivity and verify database indexing dimensions before writing the configuration.

Restart the gateway to deploy the sidecar and check its operational health:

BASH TERMINAL Copied to clipboard! 
# Restart OpenClaw to mount the active sidecar daemon
openclaw gateway restart

# Run diagnostic checks
openclaw hy-memory status

Healthy connections should report status values as follows:

TERMINAL OUTPUT 
[plugins] openclaw-hy-memory: registered (user: tom001, server: http://127.0.0.1:19527, autoRecall: true, autoCapture: true)

OpenClaw 2026.5.26 (10ad3aa) — Built by lobsters, for humans. Don't question the hierarchy.

HY Memory Server: http://127.0.0.1:19527
  Status:      ✓ healthy
  User ID:     tom001
  VDB:         ok [chroma] (collection: agent_memories_1024, points: 0)
  Embed:       ok (dims: 1024)
  LLM:         ok
  SDK Version: 1.2.5
SCHEMA STRUCTURE DEFINITION

Manual Configuration Schema

For developers who prefer writing configurations directly into OpenClaw's config.json, refer to the schema structure and variables below.

CONFIG.JSON Copied to clipboard! 
"openclaw-hy-memory": {
  "enabled": true,
  "config": {
    "userId": "tom001",
    "autoRecall": true,
    "autoCapture": true,
    "topK": 10,
    "llm": {
      "provider": "openai",
      "model": "tencent/hy3-preview",
      "apiKey": "YOUR_OPENROUTER_API_KEY",
      "baseUrl": "https://openrouter.ai/api/v1"
    },
    "embedder": {
      "provider": "openai",
      "model": "BAAI/bge-m3",
      "apiKey": "YOUR_SILICONFLOW_API_KEY",
      "baseUrl": "https://api.siliconflow.cn/v1",
      "dims": 1024
    },
    "vectorStore": {
      "provider": "chroma"
    }
  }
}
Variable Name Data Type Required Default Parameter Description
enabled Boolean REQUIRED false Enables/disables the plugin block. Setting it to true spins up the sidecar Python process.
config.userId String REQUIRED — Unique namespace identifier. Isolates separate users' datasets.
config.autoRecall Boolean OPTIONAL true Specifies whether to lookup relevant records in Chroma and insert facts to system instructions before generation.
config.autoCapture Boolean OPTIONAL true Specifies whether to extract new facts and preferences asynchronously in the background.
config.topK Number OPTIONAL 10 Defines the threshold limits for recalled items loaded during query preprocessing.
config.llm.provider String REQUIRED — API Protocol backend. Must comply with OpenAI schema standards.
config.llm.model String REQUIRED — Specific extraction model name (e.g. tencent/hy3-preview, deepseek-chat).
config.embedder.dims Number REQUIRED — Vector dimension output. Must match the designated model's configurations. (e.g., 1024 for BGE-m3).
config.vectorStore.provider String OPTIONAL chroma Underlying vector engine database. Default is embedded Chroma.
FREQUENTLY ASKED QUESTIONS

FAQ / Trouble Shooting

Explore troubleshooting guides and common answers to integration questions.

The 6-layer cognitive prompts and atomic fact schemas are fine-tuned to align with Tencent Hunyuan parameters. Using Hunyuan 3.0 Preview guarantees consistent structured outputs and prevents JSON syntax breakage.
The plugin hooks into OpenClaw's pre-chat and post-chat interceptors. Lookups occur synchronously before query processing, while extraction is processed on a worker thread after the prompt completes, guaranteeing zero stream blocking latency.
Yes. Simply assign the exact same config.userId (e.g. tom001) across different agent configuration panels. They will access the same vector namespaces and shared profile graphs.
No. The sidecar handles errors gracefully. If an API call fails or times out after 30 seconds, the extraction job will be retried or discarded safely without crashing the main OpenClaw agent instance.