Honcho Memory Multiplexer

---

name: honcho-memory-mux-setup description: > Install and enable Honcho + the @alloralabs/honcho-memory-mux extension, migrate legacy file memory, and update workspace instructions so agents use memory via Honcho-first multiplexed retrieval with local-file fallback. metadata: openclaw: emoji: "🧠" optional_env: - name: HONCHO_API_KEY description: "API key. Optional for many local/self-hosted setups." - name: HONCHO_BASE_URL description: "Base URL for self-hosted Honcho (example: http://localhost:8000)." - name: HONCHO_WORKSPACE_ID description: "Honcho workspace ID (default: openclaw)." - name: WORKSPACE_ROOT description: "OpenClaw workspace root. Auto-detected if unset." required_binaries: - node - npm optional_binaries: - git - docker - docker-compose writes_to_disk: true network_access: - "User-configured HONCHO_BASE_URL (self-hosted mode)" homepage: "https://honcho.dev" source: - "https://github.com/plastic-labs/honcho" - "https://github.com/allora-network/honcho-memory-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-)

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

2. 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

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

4. 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/.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