[Feature]: Add migration tool to import existing OpenClaw conversation history into OpenViking

[deepakdevp]

Problem Statement

When an existing OpenClaw user installs the OpenViking plugin, they start with zero memory. All past conversations, learned preferences, entities, and context accumulated over weeks or months of OpenClaw usage are lost. OpenViking only captures new interactions going forward.

This is a significant adoption barrier — users with rich conversation history get no benefit from it after enabling OpenViking.

Current Behavior

• OpenClaw stores conversation transcripts locally (in ~/.openclaw/ or the project's .openclaw/ directory)
• The OpenViking plugin (examples/openclaw-plugin/) only processes new conversations via hooks
• There is no tool or script to backfill existing transcripts into OpenViking's memory system
• Users must start from scratch, losing all accumulated context

Proposed Solution

Add a migration script/CLI command that:

1. Reads existing OpenClaw conversation transcripts from the local data directory
2. Feeds them through OpenViking's session API — create sessions, add messages, commit to trigger memory extraction
3. Runs in batch mode with progress reporting and resume capability (for large histories)

Suggested interface:

# Import all conversations from default OpenClaw data dir
ov migrate-openclaw

# Import from a specific directory
ov migrate-openclaw --source ~/.openclaw/projects/my-project/

# Dry run to show what would be imported
ov migrate-openclaw --dry-run

# Resume interrupted migration
ov migrate-openclaw --resume

Why This Matters

• OpenClaw has 336k+ stars with a massive active user base
• OpenViking's value proposition is persistent agent memory — but only for future interactions
• A migration tool dramatically improves the onboarding experience
• Users see immediate value (memories from past conversations) instead of waiting days for enough new context to accumulate
• Similar to how database migration tools exist for framework upgrades

Alternatives Considered

• Manual transcript paste: Users could paste old conversations into the OpenViking session API, but this is tedious and error-prone
• Re-run conversations: Not practical for months of history
• Export/import via MCP: MCP doesn't have a batch import protocol

Feature Area

Session / Memory / CLI

Use Case

Any OpenClaw user who installs the OpenViking plugin and wants their existing conversation context to be available for memory recall and semantic search.

[deepakdevp]

I'd like to work on this. I have experience with the session/memory pipeline from PRs #783, #734, #728, and the embedding layer from #928, #772 — happy to implement this.

I'll start with a scoped Phase 1: a Python script that reads OpenClaw transcript files, feeds them through the Session API (create → add_message → commit_async), and lets OpenViking's existing memory extraction handle the rest. Will share a design before coding.

Could a maintainer confirm this direction is welcome?

[deepakdevp]

Proposed Solution

After researching both OpenClaw's transcript storage and OpenViking's ingestion APIs, here's my proposed approach:

OpenClaw On-Disk Format

OpenClaw stores conversations at ~/.openclaw/agents/<agentId>/sessions/:

• sessions.json — index mapping sessionKey → metadata (sessionId, label, updatedAt, channel)
• <sessionId>.jsonl — JSONL transcript (header line + one message per line with role, content[], timestamp, model)

Dual-Mode Migration Script (examples/openclaw-migration/)

Resource Mode (default, cheap):

• Parse each OpenClaw transcript → convert to readable .md
• Import via client.add_resource() → auto-embeds + indexes
• 0 LLM calls — embedding only
• Past conversations become searchable immediately

Session Mode (--extract-memories, rich):

• Replay messages via client.add_message() → client.commit_session()
• Triggers full memory extraction (profiles, preferences, entities, events, patterns, tools)
• 4-5 LLM calls per session — but agent truly learns from past conversations

CLI Interface

python examples/openclaw-migration/migrate.py \
  --openclaw-dir ~/.openclaw/agents/main/sessions/ \
  [--extract-memories]   # Rich mode with LLM memory extraction
  [--dry-run]            # Preview what would be migrated
  [--sessions id1,id2]   # Filter specific sessions

Why examples/ and not an ov CLI command

The ov CLI routes through Rust — adding a Python subcommand would require special-casing in rust_cli.py. A standalone script follows the existing pattern (examples/openclaw-plugin/demo-memory-*.py) and keeps the PR surface small.

Phase 1 scope

• OpenClaw JSONL reader with error handling (corrupt lines, missing files, compaction records)
• Resource mode migration (cheap, no LLM)
• --dry-run support
• Unit tests with synthetic fixtures

Happy to start implementation if this direction looks good.

[deepakdevp]

cc @qin-ctx @MaojiaSheng @ZaynJarvis — would appreciate your thoughts on this direction before I start implementation.

[qin-ctx]

Thanks for digging into this. The overall direction looks good to me.

One priority point I'd suggest making explicit: if OpenClaw already has a reasonably stable on-disk memory / learned-state format, I think memory migration may actually be more urgent than transcript migration.

In practice, the user's immediate need is usually not just to bring over old conversation files, but to keep the memories they've already accumulated and make them usable in OpenViking right away. If that path is feasible and the format maps cleanly enough to OpenViking's memory model, I think it's worth evaluating first.

So my suggested priority is:

• Phase 1: evaluate and, if feasible, support memory migration first
• Phase 2: add transcript migration as the general fallback / complementary path

If, after investigation, OpenClaw does not expose a stable or migration-friendly memory format, then falling back to transcript replay for the first version still sounds like the right starting point.

So yes, this direction is welcome. I'd suggest first confirming how OpenClaw stores its existing memory data and whether that format is practical to migrate. If it is, I think that work deserves higher priority than transcript replay. If not, transcript migration is still a solid Phase 1.

Feel free to update the design once you've validated that part, or open a PR when you're ready.

[qin-ctx]

cc @Mijamind719 @chenjw

[deepakdevp]

(Earlier comment deleted as I dug deeper into OpenClaw's architecture and found more complete information.)

What OpenClaw actually stores (memory, not just transcripts):

Memory files at ~/.openclaw/workspace/:

• memory/YYYY-MM-DD.md — daily memory logs (agent writes durable facts during conversation)
• MEMORY.md — curated long-term memory
• memory/YYYY-MM-DD-slug.md — session summaries (auto-saved via session-memory hook on /new or /reset)

How it works:

• Agent actively writes preferences, facts, decisions to memory/*.md during conversation
• Pre-compaction flush triggers a silent agentic turn to persist durable memories before context compression
• Vector search (SQLite-vec or QMD sidecar) indexes all memory files for semantic memory_search tool
• MEMORY.md + recent daily logs are loaded at session start

Revised approach (aligned with your feedback):

Phase 1: Memory file migration — import ~/.openclaw/workspace/memory/ + MEMORY.md as OpenViking resources. These are plain Markdown, so one add_resource() call handles everything (parse → embed → index). 0 LLM calls. Immediate searchability.

Phase 2: Transcript migration — convert JSONL conversation history as a complementary, lower-priority step.

This directly addresses your point about memory being more urgent than transcripts. The memory files ARE the distilled knowledge — importing them gives immediate value.