honcho-memory-mux（honcho 记忆 MUX）

Honcho + Memory Mux Setup

This skill installs and enables: 1) @honcho-ai/openclaw-honcho (Honcho tools + integration) 2) @alloralabs/honcho-memory-mux (multiplexed memory behavior)

Then it migrates legacy memory files, updates agent docs, and validates runtime behavior.

What “memory mux” means in practice

After setup, memory behavior should be:

• Primary retrieval: Honcho tools (honcho_context, honcho_search, etc.)
• Secondary retrieval: local memory files (MEMORY.md, memory/*.md) via memory_search / memory_get
• Durability: pre-compaction flush writes significant session learnings to memory/YYYY-MM-DD.md
• Fallback safety: if Honcho is unavailable, file-based memory still works

This is intentionally complementary, not a hard cutover.

Step 0: Preflight and safety checks

Before doing anything destructive:

• Resolve workspace root from:

1. WORKSPACE_ROOT 2. ~/.openclaw/openclaw.json (agent.workspace or agents.defaults.workspace) 3. ~/.openclaw/workspace

• Confirm directory exists
• Inform user this process can upload memory files to Honcho

Step 1: Install + enable Honcho plugin

Use OpenClaw plugin manager (not workspace npm install):

openclaw plugins install @honcho-ai/openclaw-honcho
openclaw plugins enable openclaw-honcho

If gateway logs show missing SDK deps:

cd ~/.openclaw/extensions/openclaw-honcho
npm install

Restart gateway if required.

Step 2: Install + enable memory mux extension

Install and enable the memory-mux extension:

openclaw plugins install @alloralabs/honcho-memory-mux
openclaw plugins enable @alloralabs/honcho-memory-mux

If the extension is local/unpublished, install from path or git URL per your release flow.

After enabling:

• Verify plugin appears in openclaw plugins list
• Verify gateway boots cleanly (no extension load errors)
• Verify both Honcho tools and memory_search / memory_get are present at runtime

Step 3: Verify Honcho connectivity (self-hosted)

• Set HONCHO_BASE_URL (example: http://localhost:8000)
• HONCHO_API_KEY may be optional depending on auth config

If user needs local Honcho quickly:

git clone https://github.com/plastic-labs/honcho
cd honcho
cp .env.template .env
cp docker-compose.yml.example docker-compose.yml
docker compose up -d

Do not migrate until connection is verified.

Step 4: Detect and classify legacy memory files

Scan workspace for:

User/owner memory inputs

• USER.md
• IDENTITY.md
• MEMORY.md
• memory/** (recursive)
• canvas/** (recursive)

Agent/self memory inputs

• SOUL.md
• AGENTS.md (and AGENT.md if present in this workspace)
• TOOLS.md
• BOOTSTRAP.md
• HEARTBEAT.md

Present a clear preview before upload:

• count files per class
• total bytes per class
• any unreadable/skipped files

Ask for explicit confirmation.

Step 5: Upload to Honcho using peer-separated sessions

Create/ensure:

• workspace (HONCHO_WORKSPACE_ID or openclaw)
• peer owner
• peer openclaw
• migration session (e.g. migration-upload-<timestamp>)

Add both peers to session, then upload files:

• user/owner files → owner
• agent/self files → openclaw

If any upload fails:

• stop
• report exact file and error
• keep local files unchanged

Report summary:

• uploaded user file count
• uploaded agent file count
• failed/skipped files

Step 6: Update workspace docs (including AGENT.md compatibility)

Update/create memory instructions in:

• AGENTS.md
• SOUL.md
• BOOTSTRAP.md
• AGENT.md (if this workspace uses it)

Preserve custom content; only replace memory-specific sections.

Required policy text to add

1. Memory retrieval order

- First try honcho_context / honcho_search / honcho_recall - If needed, use memory_search + memory_get for local file recall - Use honcho_session for same-session recall

1. Memory write behavior

- Important durable facts can be written via honcho_write - Pre-compaction flush writes concise durable notes to memory/YYYY-MM-DD.md

1. Failure handling

- If Honcho unavailable: continue with local memory tools, state degraded mode - Never claim memory certainty without retrieval evidence

1. Transparency

- When memory influences an answer, be able to explain source class (Honcho recall vs local file recall vs current-session context)

Step 7: Add/refresh practical memory operating conventions

Ensure docs reflect these conventions the agent has been using:

• Do not preload everything into active reasoning if not needed
• Prefer targeted retrieval over huge static context injection
• Treat disagreement as signal: preserve conflicting observations; do not silently average
• Use pre-compaction flushes to avoid losing high-value context during long sessions
• Separate memory types conceptually:

- durable facts - episodic notes - scratch/working notes

Even if physical storage is mixed, behavior should preserve this distinction.

Step 8: Optional (recommended) no-fork observability add-on

Without modifying OpenClaw gateway source, the memory-mux extension can emit:

• a small memory load manifest per session start (what memory sources were pulled)
• a pre-compaction write report (what was persisted)

Store under:

• memory/manifests/YYYY-MM-DD/<session>.json

This makes memory behavior debuggable while keeping upstream updates painless.

Step 9: Validate end-to-end behavior

Run a quick live test:

1. Ask agent about a known historical fact only in migrated memory
2. Confirm retrieval path works (Honcho first, fallback available)
3. Trigger/perform pre-compaction flush
4. Confirm new note appears in memory/YYYY-MM-DD.md
5. Re-ask fact in a new turn/session to validate durability

Wrap-up report to user

Provide:

• installed/enabled plugin list
• Honcho connectivity mode (managed vs self-hosted)
• files discovered, uploaded, skipped
• docs updated (AGENTS.md, SOUL.md, BOOTSTRAP.md, AGENT.md if present)
• any follow-up actions

Reference docs:

• https://docs.honcho.dev
• https://github.com/plastic-labs/honcho

Guardrails

• Never delete user memory files automatically unless user explicitly asks
• Never proceed with migration on failed Honcho connectivity
• Never silently ignore upload errors
• Prefer reversible edits and clear summaries