lcm-import

Backfill all your existing OpenClaw session history into lossless-claw (LCM — Lossless Context Management).

By default, the LCM plugin only captures conversations going forward from when you install it. This tool imports your previous sessions so nothing is lost.

---

What it does

• Reads all .jsonl session files from your OpenClaw sessions directory
• Imports every message into the LCM SQLite database
• Indexes everything for full-text search (lcm_grep, lcm_expand, lcm_describe)
• Handles edge cases: malformed surrogates, empty sessions, already-imported sessions
• Idempotent — safe to run multiple times, skips sessions already in the DB
• Atomic — each session is a single transaction; one bad session won't corrupt others
• Creates a timestamped backup of your DB before writing anything

---

Prerequisites

1. OpenClaw installed and running
2. lossless-claw plugin installed:

   openclaw plugins install @martian-engineering/lossless-claw
   openclaw gateway restart

3. Python 3.9+ (standard library only — no pip installs needed)

---

Usage

Step 1 — Dry run (validate, no writes)

Always run this first:

python3 lcm_import.py --dry-run

You'll see every session listed with message counts and any parse errors. Nothing is written to disk.

Step 2 — Import

python3 lcm_import.py

A timestamped backup of your lcm.db is created automatically before any writes.

Step 3 — Verify

sqlite3 ~/.openclaw/lcm.db \
  "SELECT COUNT(*) AS conversations FROM conversations;
   SELECT COUNT(*) AS messages FROM messages;"

---

Options

--dry-run          Validate all sessions without writing to DB
--sessions-dir     Path to JSONL session files
                   (default: ~/.openclaw/agents/main/sessions)
--db               Path to LCM SQLite DB
                   (default: ~/.openclaw/lcm.db)

---

Schema note

If you install lossless-claw and run openclaw gateway restart but haven't had any conversations yet, the LCM database tables may not exist yet. The script will detect this and exit with an error. Fix: send one message to your agent first, then run the import.

Alternatively, the script will work fine if you manually trigger the gateway to bootstrap the DB by sending any message after installing the plugin.

---

What gets imported

Table	What
conversations	One row per session file
messages	Every user/assistant/tool message
message_parts	Text, reasoning, tool calls, tool results, images
messages_fts	Full-text search index

Not imported: summaries, summary_parents, context_items — these are built by the LCM plugin at runtime as new messages arrive and trigger compaction. No need to reconstruct them manually.

---

JSONL format compatibility

Tested against OpenClaw session files with:

• user, assistant, toolResult roles
• text, thinking, toolCall, image content part types
• Lone surrogate characters in content (sanitized automatically)

---

Safety

• Backup created at ~/.openclaw/lcm.db.bak.YYYYMMDD_HHMMSS before any writes
• Foreign key enforcement enabled during import
• WAL journal mode for crash safety
• Each session wrapped in BEGIN IMMEDIATE … COMMIT — rollback on any error
• Sessions already in the DB are skipped (idempotent)

---

Example output

=== DRY RUN MODE — no writes will occur ===

Found 27 session file(s) in /Users/you/.openclaw/agents/main/sessions

[abc123...]
  294 messages to import
  DRY-RUN OK — 294 messages, 377 parts

[def456...]
  867 messages to import
  DRY-RUN OK — 867 messages, 1224 parts

...

============================================================
IMPORT SUMMARY
============================================================
  Sessions imported:  27
  Sessions skipped:   0
  Sessions errored:   0
  Total messages:     13722
  Total parts:        16516

  DRY RUN complete — no data written.
  Run without --dry-run to import.

---

License

MIT