L-clone

🧠 L-clone — External Brain

中文 | English

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 3-segment form — point ｜ background/why ｜ impact/what to watch for — so each is independently readable; references to evolution assets or specs are written inline
• 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, keeping the last N versions — default 5, current version never pruned); ~/.lclone/evolution/ is only a reproducible read-only cache (pull / publish / status) that an insight points to with [[evo:name.ext]]. The store holds data and executables only — specs, rules and prose belong in insights, and evolution audit only flags suspected misfiling
• 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 2 example scripts (published as evolution assets; seeds contain no prose documents) — 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
• Project identity is the git remote: a project is keyed by its normalized origin (host/group/repo), the local path is only "where it was last seen"; duplicates are found with proj dupes and merged with proj merge (rollback-able)
• Delete in two steps: evolution delete / proj rm only move an object to the recycle bin (a tombstone you can restore); only purge is permanent — irreversible, no backup, and accepted only for objects already in the bin. Purging a project keeps its review_log trail (admission precision is computed from it) and unbinds its evolution assets instead of deleting them
• 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 backend service (admission gate + core logic — pure functions) and the storage & model layers:

Interactive version — pan/zoom, search, guided chapters (write path / read path / two-step delete / entry points), light & dark, PNG & SVG export: docs/diagrams/lclone-architecture.html. It is generated from docs/diagrams/lclone-architecture.json, where every node is bound to the source file it was verified against.

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 for the data model (ER), the write/recall/spec flows, and the design rationale.

Dependencies

Install:

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.

How to use

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

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

One-click deploy (recommended)

# 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):

$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:

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):

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:

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)

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://<server-ip>:8000/
• Q&A page: http://<server-ip>: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:

dsh plugin --profile web add @yueliudan/lclone-memory-dsh -w

• npm: https://www.npmjs.com/package/@yueliudan/lclone-memory-dsh
• 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:

export LCLONE_WEB_URL=http://<server-ip>:8000
export LCLONE_API_KEY=<LCLONE_API_KEY from the server .env>

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 <name> 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

lclone backup                                  # local: consistent snapshot via the backup API (WAL-safe)
scp backups/lclone-<timestamp>.db root@<server>:/repo/data/lclone.db.new   # upload to a temp name
ssh root@<server> '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

License

LICENSE · MIT License · Copyright (c) 2026 ljzRober