ljzRober/L-clone

🧠 L-clone — 外置大脑 (External Brain)

License: MIT

L-clone 是一个个人外置大脑:记录你做过什么,并在你规划未来时调用记忆、监督方案的边界条件。

它做了什么

- 分层记忆:会话流水(L0)→ 洞察(L1)→ 项目 spec 索引(L2)
- 洞察而非流水账:每条记忆是原子化、自包含的知识卡(一个决定/一条经验/一个观察/一条教训),按三段卡书写——要点 ｜ 背景/为什么 ｜ 影响/以后注意,独立可读;指向进化资产/契约的引用就地写在正文里
- 回顾环:新会话自动召回相关洞察,回答"我上次做到哪、定了什么"
- 规范环:新提议对照项目 spec 的边界条件,输出 ✅通过 / ⚠️警告 / ❌违反 检查报告
- 写入方式:自动捕获(B, AI 提炼→你确认)与主动记忆(C, 你说算);洞察一律经你盖章才生效,每条可追溯来源
- 进化资产:可复用的脚本/工具/模板存进服务器侧版本化内容寻址库(sha256 命名、只追加、可回滚),本地 ~/.lclone/evolution/ 只是可复现的只读缓存(带 manifest,支持 pull/publish/status);洞察用 [[evo:name.ext]] 指向
- 准入与整理:确定性准入闸门先判(纯脚本、不调 LLM,skip 档零调用)、只收"决策/约定/规则/教训",再看用户轮并遵循否定作用域;代码强制过滤"做了什么"(归 git/spec, 不进大脑)、洞察矛盾检测、organize 一键语义合并相近洞察
- 开箱即用:首次 setup 自动种入 4 条通用洞察 + 通用进化文件(洞察格式模型 / 记忆准入标准 / 会话归属约定 + 示例脚本),幂等且删掉不回灌
- 两轴竖向分层:全局层 → 项目;具体事务留在仓库,大脑只管方向和决策
- 多端接入:CLI + Web 面板 + REST API + MCP(Claude Code / Codex / DSH 插件),一条 install 向导接入

它解决了什么问题

模型是无状态的:下次对话,AI 不记得你上次的决定、项目的边界和规格。
L-clone 把"你做过什么、定过什么、约束是什么"沉淀为持久记忆,在每次新会话注入,
让 AI 的下一步工作建立在"你之前的决策"之上,而不是每次从零开始。

架构总览

L-clone 将访问层(CLI / Web / REST API / MCP)与核心逻辑(记忆 / 项目 / 问答 / 监督,纯函数)以及存储层与模型层分离:

flowchart TB
subgraph 访问层["访问层 (任何设备 / 浏览器 / AI 工具)"]
CLI["CLIinit / proj / remember / capture / evolution / review / recall / conflicts / ask / supervise"]
WEB["Web 面板记忆工作台(层级树+架构图) + 问答页FastAPI + 单页 HTML"]
API["REST API/api/ask /api/capture /api/organize /api/supervise ..."]
MCP["MCPstdio + HTTP(/mcp)Claude Code / Codex / DSH 接入"]
end

subgraph 核心["核心逻辑 (纯函数, 与访问层解耦)"]
MEM["记忆模块remember(C) / capture(B) / review / recall / conflicts / organize"]
PROJ["项目模块proj add / sync / rm / restore / spec 格式无关索引"]
CHAT["问答模块回顾环"]
SUPE["监督模块规范环"]
end

subgraph 存储["存储层"]
DB[("SQLite lclone.dbprojects / sessions / insights / specs_indexthreads / messages / memory_links / recall_logproject_removals / memories_fts")]
EVO[("data/evolution/ + evo_versions (服务器权威, 版本化)~/.lclone/evolution/ 只是只读缓存, 由 [[evo:name.ext]] 链接")]
end

subgraph 模型["模型层 (云端 API, 不本地部署)"]
LLM["LLM提炼 / 问答 / 监督"]
EMB["Embedding向量化洞察用于召回"]
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 -. 只读索引 .-> REPO["项目仓库.specs/ 与 doc/adr/ (权威内容)"]
MEM --> EMB & LLM
CHAT --> LLM
SUPE --> LLM

BRAIN_LLM=dummy 时模型层由内置离线后端替代, 无需网络与 API Key。

数据模型(ER)、写入/回顾/规范等流程与时序图、设计取舍,详见 docs/CONCEPTS.md。

需要什么依赖

| 项 | 要求 |
|---|---|
| Python | >= 3.10(无需 GPU) |
| 第三方库 | openai(>=1.30)/ fastapi(>=0.110)/ uvicorn(>=0.29)/ questionary(>=2.0, 交互式菜单) |
| 数据库 | SQLite(内置,无需安装) |
| 网络 | 模型 API 需能访问 BRAIN_BASE_URL;国内装依赖推荐清华镜像 |
| 离线模式 | BRAIN_LLM=dummy:零第三方依赖、无需 API Key,可完整体验全部功能 |

安装:

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

提示: 装依赖建议用 python -m pip 而不是 .venv\Scripts\pip——后者是启动器, venv 被移动/改名后会失效(Fatal error in launcher)。

部署后端服务用 lclone setup(选 provider + 填 key → 生成 .env、初始化数据库, 空项目起步),不注册项目、不碰任何 AI 工具前端;接入 Claude Code / Codex / DSH 另用 lclone integrate。详见 docs/CLI.md。

如何使用

一键体验(离线, 3 分钟, 零依赖)

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

一键部署(推荐)

本地(Windows / macOS / Linux 通用): 建 venv + 装依赖 + 接入向导 + 自检 + 启动 web
python scripts/deploy_local.py            # 交互式选 provider + 填 key
python scripts/deploy_local.py --offline  # 离线模式, 零依赖零 key
python scripts/deploy_local.py --mirror   # 国内用清华镜像装依赖

服务器(Linux + Docker): 交互生成 .env → docker compose up -d --build → 健康检查
./scripts/deploy_server.sh

手动流程

第 1 步 — 离线模式先跑通(无需 API Key):

$env:BRAIN_LLM = "dummy"        # 离线模式
python -m lclone init
python -m lclone proj add demo examples/demo_project --charter "示例项目"
python -m lclone proj sync demo          # 扫描并索引项目里的 spec 文件
python -m lclone remember "后端用 FastAPI, 边界: 单用户" --project demo
↑ 洞察默认进待确认; 加 --confirmed 直接生效, 或稍后 review 确认
python -m lclone capture "讨论后确定: 6月1日上线" --project demo
python -m lclone review --all keep       # 确认草稿 (或交互式: lclone review)
python -m lclone recall "FastAPI" --project demo
python -m lclone supervise "把数据库换成 PostgreSQL" --project demo
python -m lclone conflicts               # 找出互相矛盾的洞察对 (需真实 LLM 判定)
python -m lclone ask "我们项目定了什么?" --project demo

注意:remember 只写洞察(已无独立的 note 级——过程性事实记录并入了 evolution / git 侧)。要沉淀可复用脚本/工具,用 lclone evolution add。

第 2 步 — 接入真实模型 API + Web 面板:

python -m lclone setup              # 部署后端: 选 provider + 填 key, 自动写 .env (推荐)
或手动: Copy-Item .env.example .env, 填 OPENAI_API_KEY / BRAIN_BASE_URL / 模型名 (见 docs/CLI.md)
python -m lclone doctor --check-llm  # 自检接入是否完整
.\.venv\Scripts\python.exe -m lclone web    # 浏览器打开 http://127.0.0.1:8000
后台常驻: lclone serve start / stop / status / restart
接入 Claude Code / Codex / DSH 等 AI 工具(可选, 单独命令): lclone integrate

记录与 Claude/AI 的对话

把对话内容粘给大脑,它自动提炼洞察(进草稿,你确认后生效):

lclone capture "我想做个健身记录工具。Claude 建议: 用 Python + SQLite, 每周自动汇总, 先跑通再优化。我同意, 定于下月 1 号上线。"
lclone review --all keep        # 你过目后确认洞察草稿
lclone recall "健身工具"         # 下次直接想起

不想粘长对话?让 Claude 在结尾输出一行结论,然后:

lclone remember "健身工具: Python+SQLite, 每周汇总, 下月1号上线" --confirmed   # 洞察当场已确认, 直接生效

记不清 --confirmed 也没关系:洞察不确认就进待确认,lclone review 再盖章同样生效。
Web 面板「记忆工作台」的「待确认」按钮也可处理;接入 AI 工具(lclone integrate 配置 MCP / DSH 插件 / Claude Code hooks)后无需复制粘贴,自动沉淀。

完整自测(无需 API Key)

python tests/test_offline.py    # 90+ 项离线自测, 无需 API Key

前端下载与多端远程访问

后端(记忆在服务器)与前端(访问层)分离:前端可从 npm(DSH 插件市场)下载,也可直接用浏览器打开后台自带的 Web 面板。

浏览器打开 Web 面板
后台起来后(docker compose up -d)直接访问:
- 记忆工作台: http://:8000/
- 问答页: http://:8000/ask

前端(DSH 大脑看板)从 npm 下载
DSH 的「大脑看板」前端是独立 npm 插件,一条命令安装:
dsh plugin --profile web add @yueliudan/lclone-memory-dsh -w
- npm 市场:
- 装完重启 DSH;插件默认连 http://127.0.0.1:8000,部署到服务器时用环境变量指向。

指向远程后台(环境变量)
启动 DSH 前设置:
export LCLONE_WEB_URL=http://:8000
export LCLONE_API_KEY=

鉴权与「免输 key」
- 服务器 .env 的 LCLONE_API_KEY 非空 → /api/* 与 /mcp 全部要求鉴权(不带 key 返回 401)。
- 多设备 token:lclone auth create  按设备发独立 token(库里只存 sha256 哈希、可单独吊销),lclone auth list/revoke/test 管理;触发条件为"设了 env key 或库中已有 token"。
- DSH 插件(自动带 key, 自 v0.2.2 起):从环境变量读 key,经 postMessage 注入看板,看板免手输自动加载。
- 浏览器直接打开面板:顶部 API Key 框粘贴一次 key 回车(存 localStorage,之后免输)。
- 想彻底免 key:把 .env 的 LCLONE_API_KEY 留空 + 用防火墙/Tailscale 只放行你的 IP,所有端零 key。

从本地迁移数据到服务器
lclone backup                                  # 本地: 用备份 API 生成一致快照(WAL 安全)
scp backups/lclone-.db root@:/repo/data/lclone.db.new   # 传到临时名
ssh root@ 'cd /repo && docker compose down && mv data/lclone.db.new data/lclone.db && docker compose up -d'
迁移不要直接 cp 正在写入的库文件;用 lclone backup(走 SQLite 在线备份 API)更稳。

文档索引

| 文档 | 内容 |
|---|---|
| docs/CONCEPTS.md | 设计理念(分层、双环、洞察确认、进化资产)、Mermaid 图(数据模型/写入/回顾/规范/竖向)、生态、路线图 |
| docs/CLI.md | CLI 完整命令参考、Web 面板与 REST API、模型 API 配置、环境变量 |
| docs/DEPLOYMENT.md | 服务器部署(Docker + Caddy + 安全)与 MCP over HTTP |

开源协议

LICENSE · MIT License · Copyright (c) 2026 ljzRober