Soul Mirror Scribe

Name: Soul Mirror Scribe
Rating: 3.5 (1 reviews)
Author: PrentissLiu

By PrentissLiu 👁 3 views ▲ 0 votes

OpenClaw’s full‑memory indexing plugin — one‑click indexing for all chat logs

GitHub

Install

openclaw plugins install -l

README

# soul-mirror-scribe

**OpenClaw’s full‑memory indexing plugin — one‑click indexing for all chat logs.**

Soul Mirror Scribe converts OpenClaw session `jsonl` into structured Markdown, then feeds QMD for fast search. It fixes the common pain point: QMD only indexes `/memory`, while raw session logs live elsewhere.

---

## Why
- QMD does **not** index all chat sessions by default.
- Vector search over raw `jsonl` is noisy and incomplete.
- This plugin builds clean Markdown with tags and corrections, then QMD can index everything reliably.

## Features
- **jsonl → Markdown** (Summary Hall + Archive Vault)
- **Tags + importance** per line
- **Correction & repair flow** (ledger-backed)
- **Global search** across sessions
- **Sync-thought** cross‑session topic archive
- Built‑in `sync.sh` orchestration (scan/update/embed)

---

## Prerequisites
- OpenClaw installed and running.
- **QMD configured** (required). You must already have a working QMD setup.

Verified QMD paths (example):
- `models/qmd-cache/qmd/models`

> If your QMD lives elsewhere, set it in your environment or config; this is just a known‑working reference.

---

## Install (GitHub repo → OpenClaw plugin)
```bash
# 1) Clone
git clone https://github.com/PrentissLiu/soul-mirror-scribe.git

# 2) Install into OpenClaw (dev link)
openclaw plugins install -l ./soul-mirror-scribe

# 3) Enable
openclaw plugins enable soul-mirror-scribe
```

Alternative (copy install):
```bash
openclaw plugins install ./soul-mirror-scribe
```

> After enabling, restart the Gateway if needed.

---

## Default paths
Outputs:
- Summary Hall: `~/clawd/memory/sessions/YYYY-MM/YYYY-MM-DD/YY-MM-DD-<session-id>.md`
- Archive Vault: `~/clawd/memory/sessions-archive/YYYY-MM/YYYY-MM-DD/YY-MM-DD-<session-id>.md`

Inputs & state:
- Sessions: `~/.openclaw/agents/main/sessions/*.jsonl`
- State: `~/.openclaw/memory/soul-mirror-scribe.state.json`
- Tag Rules: `~/clawd/memory/state/session_tag_rules.json`
- Tag Overrides: `~/clawd/memory/state/session_tag_overrides.json`
- Tag Reason Ledger: `~/clawd/memory/state/tag_reason_ledger.jsonl`
- Timezone: `Asia/Shanghai` (configurable)

---

## Commands
Status:
```bash
openclaw soul-mirror status
```

Full scan:
```bash
openclaw soul-mirror scan --full
```

Incremental scan:
```bash
openclaw soul-mirror scan
```

Watch (polling):
```bash
openclaw soul-mirror watch --poll-ms 5000
```

Tag & correct:
```bash
openclaw soul-mirror tag <session-id> --lines 12-15
openclaw soul-mirror tag <session-id> --lines 2,8,19-23 --tags "favorite,important_fact"
openclaw soul-mirror tag <session-id> --lines 90-95 --tags "correction,shadow_ops" --reason "Commander asleep" --fact "NO_PROXY patch by Shadow"
openclaw soul-mirror correct <session-id> --lines 90-95 --note "Corrected: NO_PROXY patch by Shadow."
openclaw soul-mirror repair
```

Summarize:
```bash
openclaw soul-mirror summarize <session-id>
openclaw soul-mirror summarize <session-id> --tone warm
openclaw soul-mirror summarize <session-id> --agent shadow
openclaw soul-mirror summarize <session-id> --fallback-local
```

Search (global + related):
```bash
openclaw soul-mirror search "dinner"
openclaw soul-mirror search "dinner" --global
openclaw soul-mirror search "dinner" --with-related
openclaw soul-mirror search "dinner" --with-related --json
openclaw soul-mirror search "dinner" --with-wisdom --json
```

Sync-thought (topic archive):
```bash
openclaw soul-mirror sync-thought "dinner"
openclaw soul-mirror sync-thought "dinner" --expires-after 30d
openclaw soul-mirror sync-thought "dinner" --refresh
openclaw soul-mirror sync-thought "dinner" --session <session-id>
```

Output path:
- `~/clawd/memory/thought-archive/<Topic>/<Topic>_YYYYMMDD-HHmm.md`

---

## QMD collections
### memory-sessions (main)
```bash
qmd collection add ~/clawd/memory/sessions --name memory-sessions --mask "**/*.md"
qmd update
qmd embed
```

### memory-synthesis (optional)
```bash
qmd collection remove memory-synthesis
qmd collection add ~/clawd/memory/thought-archive --name memory-synthesis --mask "**/*.md"
qmd update
```

---

## Built-in orchestration script
```bash
# incremental scan
./scripts/sync.sh scan -- --max-files 10 --quiet

# only update qmd
./scripts/sync.sh update

# only embed
./scripts/sync.sh embed

# scan + update + embed
./scripts/sync.sh all
```

## Smoke test
```bash
./tests/smoke.sh
# or
./tests/smoke.sh ~/.openclaw/agents/main/sessions /tmp/soul-mirror-scribe-smoke
```

Cron:
```bash
./scripts/sync.sh install-cron
./scripts/sync.sh show-cron
./scripts/sync.sh uninstall-cron
```

Custom schedules:
```bash
./scripts/sync.sh install-cron \
  --scan "*/10 * * * *" \
  --update "15 * * * *" \
  --embed "40 */8 * * *"
```

---

## Notes
- QMD only indexes `/memory` by default. This plugin makes full chat history searchable by converting session jsonl into Markdown inside `/memory`.
- Archive Vault contains `<details>` with raw JSON for debugging.

---

# 中文说明（简要）
**OpenClaw 的全量记忆索引插件，一键索引所有聊天记录。**

## 前置条件
- 已配置并可用的 QMD（必须）。
- 已验证示例路径：`models/qmd-cache/qmd/models`（仅供参考）。

## 安装
```bash
git clone https://github.com/PrentissLiu/soul-mirror-scribe.git
openclaw plugins install -l ./soul-mirror-scribe
openclaw plugins enable soul-mirror-scribe
```

## QMD 集合
```bash
qmd collection add ~/clawd/memory/sessions --name memory-sessions --mask "**/*.md"
qmd update
qmd embed
```

## 冒烟测试
```bash
./tests/smoke.sh
```

---

## License
MIT

tools