l-clone

1. 安装并启动 DeepSeek Harness：npx @deepseek-ai/dsh web
2. 在终端执行上面的安装命令（CLI 会解析插件并核验来源）
3. 用 dsh plugins list 确认已安装，必要时重启 Harness 生效

插件以当前 dsh 进程的权限运行，安装时可能执行代码。请先通读仓库源码与许可证，确认无破坏性命令与越权访问；本站只做索引，不对第三方插件安全性作担保。

事实信息来自公开插件目录快照（2026-10-01），介绍文案由本站再加工。

以下为插件仓库 README 全文（原始内容，由公开目录抓取整理）。

# 🧠 L-clone — External Brain

> [中文](README.zh-CN.md) | `English`

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

**L-clone** is a personal external brain: it records what you've done, and recalls your memory and checks the boundary conditions of your proposals when you plan what's next.

## What it does

- **Layered memory**: session stream (L0) → insights (L1) → project spec index (L2)
- **Insight, not raw recording**: every memory is an **atomic, self-contained knowledge card** (a decision / an experience / an observation / a lesson) written in a 4-segment form — *point ｜ background/why ｜ impact/what to watch for ｜ attribution* — so each is independently readable
- **Recall loop**: new sessions automatically recall related insights and answer "where did I leave off / what did we decide"
- **Spec loop**: new proposals are checked against a project spec's boundary conditions, producing a ✅ pass / ⚠️ warn / ❌ fail report
- **Write modes**: automatic capture (B, AI distills → you confirm) and active memory (C, your call); **insights take effect only after you approve them** — every entry is traceable to its source
- **Evolution assets**: reusable scripts / tools / templates live in a **server-side versioned content-addressed store** (sha256-named, append-only, rollback-able); `~/.lclone/evolution/` is only a reproducible **read-only cache** (`pull` / `publish` / `status`) that an insight points to with `[[evo:name.ext]]`
- **Admission & organization**: a **deterministic admission gate** runs first (pure script, no LLM — the `skip` tier costs zero calls) and only accepts decisions / agreements / rules / lessons, judged on user turns with negation scoping; then code-enforced filtering of "what was done" (goes to git/spec, not the brain), **conflict detection** between insights, and an `organize` action that merges semantically-similar insights in one click
- **Works out of the box**: the first `setup` seeds 4 generic insights plus generic evolution files (insight format model / admission standard / attribution conventions + example scripts) — idempotent, and deleted seeds are never re-added
- **Two-axis vertical layering**: global → project; concrete work stays in the repo, the brain only tracks direction and decisions
- **Multi-client**: CLI + Web panel + REST API + MCP (Claude Code / Codex / DSH plugin), wired up via a single `install` wizard

## The problem it solves

Models are stateless: in the next conversation, the AI doesn't remember your last decisions, your project boundaries, or your specs.
L-clone settles "what you did, what you decided, what the constraints are" into durable memory and injects it into every new session, so the AI's next steps build on *your previous decisions* instead of starting from scratch each time.

## Architecture overview

L-clone separates the **access layer** (CLI / Web / REST API / MCP) from the **core logic** (memory, projects, ask, supervise — pure functions) and the **storage & model layers**:

```mermaid
flowchart TB
    subgraph 访问层["Access layer (any device / browser / AI tool)"]
        CLI["CLI
init / proj / remember / capture / evolution / review / recall / conflicts / ask / supervise"]
        WEB["Web panel
memory workbench (tree + graph) + Q&A
FastAPI + single-page HTML"]
        API["REST API
/api/ask /api/capture /api/organize /api/supervise ..."]
        MCP["MCP
stdio + HTTP(/mcp)
Claude Code / Codex / DSH integration"]
    end

    subgraph 核心["Core logic (pure functions, decoupled from access)"]
        MEM["Memory
remember(C) / capture(B) / review / recall / conflicts / organize"]
        PROJ["Projects
proj add / sync / rm / restore / spec-format-agnostic index"]
        CHAT["Ask module
recall loop"]
        SUPE["Supervise module
spec loop"]
    end

    subgraph 存储["Storage"]
        DB[("SQLite lclone.db
projects / sessions / insights / specs_index
threads / messages / memory_links / recall_log
project_removals / memories_fts")]
        EVO[("data/evolution/ + evo_versions (server-authoritative, versioned)
~/.lclone/evolution/ is just a read-only cache, linked by [[evo:name.ext]]")]
    end

    subgraph 模型["Model layer (cloud API, not self-hosted)"]
        LLM["LLM
distill / ask / supervise"]
        EMB["Embedding
vectorize insights for recall"]
    end

    CLI --> MEM & PROJ & CHAT & SUPE
    WEB --> MEM & PROJ & CHAT & SUPE
    API --> MEM & PROJ & CHAT & SUPE
    MCP --> MEM & PROJ & CHAT & SUPE
    MEM --> DB & EVO
    PROJ --> DB
    CHAT --> DB
    SUPE --> DB
    PROJ -. read-only index .-> REPO["Project repo
.specs/ & doc/adr/ (authoritative)"]
    MEM --> EMB & LLM
    CHAT --> LLM
    SUPE --> LLM
```

> With `BRAIN_LLM=dummy` the model layer is replaced by a built-in offline backend — no network and no API key needed.

See [docs/CONCEPTS.md](docs/CONCEPTS.md) for the data model (ER), the write/recall/spec flows, and the design rationale.

## Dependencies

| Item | Requirement |
|---|---|
| **Python** | **>= 3.10** (no GPU required) |
| **Third-party libs** | `openai` (>=1.30) / `fastapi` (>=0.110) / `uvicorn` (>=0.29) / `questionary` (>=2.0, interactive menus) |
| **Database** | SQLite (built-in, nothing to install) |
| **Network** | The model API must be reachable at `BRAIN_BASE_URL`; use the Tsinghua mirror for installing dependencies in China |
| **Offline mode** | `BRAIN_LLM=dummy`: zero third-party deps, no API key needed, full feature experience |

Install:

```bash
python -m venv .venv
# Windows: .venv\Scripts\python.exe -m pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
.venv/bin/python -m pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
```

> Tip: use `python -m pip` rather than `.venv\Scripts\pip` — the latter is a launcher that breaks when the venv is moved or renamed (`Fatal error in launcher`).

> Deploy the backend with **`lclone setup`** (pick a provider + enter a key → generates `.env`, initializes the database, **start from an empty project**); it does not register projects or touch any AI-tool frontend. To hook up Claude Code / Codex / DSH, use **`lclone integrate`**. See [docs/CLI.md](docs/CLI.md).

## How to use

### One-click experience (offline, 3 minutes, zero deps)

```powershell
powershell -ExecutionPolicy Bypass -File .\scripts\demo_offline.ps1
```

### One-click deploy (recommended)

```bash
# Local (Windows / macOS / Linux): create venv + install deps + setup wizard + self-check + start web
python scripts/deploy_local.py            # interactive: pick provider + enter key
python scripts/deploy_local.py --offline  # offline mode, zero deps, zero key
python scripts/deploy_local.py --mirror   # use the Tsinghua mirror in China

# Server (Linux + Docker): generate .env interactively → docker compose up -d --build → health check
./scripts/deploy_server.sh
```

### Manual workflow

**Step 1 — get it running offline first** (no API key):

```powershell
$env:BRAIN_LLM = "dummy"        # offline mode
python -m lclone init
python -m lclone proj add demo examples/demo_project --charter "示例项目"
python -m lclone proj sync demo          # scan and index the spec files in the project
python -m lclone remember "后端用 FastAPI, 边界: 单用户" --project demo
#   ↑ insights go to pending by default; add --confirmed to apply immediately, or confirm later with review
python -m lclone capture "讨论后确定: 6月1日上线" --project demo
python -m lclone review --all keep       # confirm drafts (or interactive: lclone review)
python -m lclone recall "FastAPI" --project demo
python -m lclone supervise "把数据库换成 PostgreSQL" --project demo
python -m lclone conflicts               # find contradictory insight pairs (needs a real LLM)
python -m lclone ask "我们项目定了什么?" --project demo
```

> Note: `remember` only writes **insights** (there is no longer a separate `note` level — process fact-records were folded into the evolution / git-side). To register a reusable script/tool, use `lclone evolution add`.

**Step 2 — hook up a real model API + the Web panel**:

```powershell
python -m lclone setup              # deploy backend: pick provider + enter key, auto-writes .env (recommended)
# or manually: Copy-Item .env.example .env, fill in OPENAI_API_KEY / BRAIN_BASE_URL / model name (see docs/CLI.md)
python -m lclone doctor --check-llm  # self-check the integration
.\.venv\Scripts\python.exe -m lclone web    # open http://127.0.0.1:8000 in a browser
# run in background: lclone serve start / stop / status / restart
# hook up Claude Code / Codex / DSH etc. (optional, separate command): lclone integrate
```

### Recording a conversation with Claude/AI

Paste the conversation into the brain and it automatically extracts an insight (goes to drafts, active after you confirm):

```powershell
lclone capture "我想做个健身记录工具。Claude 建议: 用 Python + SQLite, 每周自动汇总, 先跑通再优化。我同意, 定于下月 1 号上线。"
lclone review --all keep        # confirm the insight drafts after you review them
lclone recall "健身工具"         # it comes back next time
```

Don't want to paste a long conversation? Have Claude output a one-line conclusion at the end, then:

```powershell
lclone remember "健身工具: Python+SQLite, 每周汇总, 下月1号上线" --confirmed   # insight already confirmed, applies immediately
```

> If you forget `--confirmed`, it's fine: unconfirmed insights go to pending, and `lclone review` stamps them later to the same effect.
> The Web panel's "Memory Workbench" → "Pending" button also handles this; once you integrate AI tools (`lclone integrate` configures MCP / DSH plugin / Claude Code hooks) there's no copy-pasting — it's captured automatically.

### Full self-test (no API key)

```bash
python tests/test_offline.py    # 90+ offline assertions, no API key
```

## Frontend download & multi-device remote access

The backend (memory on the server) is decoupled from the access layer: the frontend can be installed from **npm (DSH plugin marketplace)**, or you can just open the Web panel the backend serves.

### Open the Web panel in a browser
After the backend is up (`docker compose up -d`), visit:
- Memory workbench: `http://:8000/`
- Q&A page: `http://:8000/ask`

### Install the frontend (DSH brain-board plugin) from npm
The DSH "brain board" frontend is a standalone npm plugin; install it with one command:
```bash
dsh plugin --profile web add @yueliudan/lclone-memory-dsh -w
```
- **npm**:
- Restart DSH after install; the plugin defaults to `http://127.0.0.1:8000` — point it at the server via environment variables.

### Point it at a remote backend (environment variables)
Set these before launching DSH:
```bash
export LCLONE_WEB_URL=http://:8000
export LCLONE_API_KEY=
```

### Auth & "no-typing key"
- If the server `.env` sets `LCLONE_API_KEY`, `/api/*` and `/mcp` require it (401 without a key).
- **Per-device tokens**: `lclone auth create ` issues an independent token (only its `sha256` hash is stored; revocable individually); manage with `lclone auth list/revoke/test`. Auth is enforced when the env key is set or any token exists.
- **DSH plugin (auto-carries the key, from v0.2.2)**: reads the key from the environment and injects it into the board via postMessage, so the board loads with no manual input.
- **Opening the panel directly in a browser**: paste the key once in the top **API Key** box and press Enter (stored in localStorage, remembered afterwards).
- To drop the key entirely: leave `LCLONE_API_KEY` empty and restrict access by firewall/Tailscale IP allowlist.

### Migrate data from local to server
```bash
lclone backup                                  # local: consistent snapshot via the backup API (WAL-safe)
scp backups/lclone-.db root@:/repo/data/lclone.db.new   # upload to a temp name
ssh root@ 'cd /repo && docker compose down && mv data/lclone.db.new data/lclone.db && docker compose up -d'
```
> Never `cp` a live database file; use `lclone backup` (SQLite online backup API).

## Documentation index

| Doc | Content |
|---|---|
| [docs/CONCEPTS.md](docs/CONCEPTS.md) | Design rationale (layering, the two loops, insight confirmation, evolution), Mermaid diagrams (data model / write / recall / spec / vertical), ecosystem, roadmap |
| [docs/CLI.md](docs/CLI.md) | Full CLI reference, Web panel & REST API, model API config, environment variables |
| [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md) | Server deployment (Docker + Caddy + security) and MCP over HTTP |

## License

[LICENSE](LICENSE) · **MIT License** · Copyright (c) 2026 ljzRober