diff --git a/README.md b/README.md
index 9176dd2..c31fb72 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,9 @@
 # call-code
 
+<p align="center">
+  <img src="packages/client/assets/call-code.png" alt="call-code 产品标识" width="240" />
+</p>
+
 ![Node.js](https://img.shields.io/badge/Node.js-20%2B-339933?logo=nodedotjs&logoColor=white)
 ![TypeScript](https://img.shields.io/badge/TypeScript-3178C6?logo=typescript&logoColor=white)
 ![pnpm](https://img.shields.io/badge/pnpm-F69220?logo=pnpm&logoColor=white)
@@ -15,6 +19,8 @@ call-code 是一个本地运行的终端编程 Agent（CLI coding agent），基
 - 结构化响应协议：模型输出统一为 `tool_call` 或 `final` 的 JSON action，循环解析并继续执行。
 - 本地记忆：短期记忆按任务保存，长期记忆按主题沉淀，仅在进程内使用，不写入本地 JSON。
 - 上下文预算：运行时基于 token 估算对历史消息做裁剪，减少超出模型上下文的风险。
+- 会话持久化：基于 Node 内置 `node:sqlite` 保存会话、条目、泳道、分支、记录、统计、事实和租约，默认写入 `.agent-sessions/sessions.db`。
+- 会话展示端：`packages/client` 提供 React + Vite 静态页面，可把会话数据导出为 JSON 后部署到 GitHub Pages。
 
 ## 架构
 
@@ -64,22 +70,34 @@ packages/
       policy/                # PLAN/BUILD 模式下的工具权限
       web/                   # GitHub Pages 客户端数据导出
   client/                    # TypeScript + React 会话历史界面，可部署到 GitHub Pages
+  session-sqlite/            # 基于 node:sqlite 的会话历史与运行状态存储
 tests/                        # 项目统一单元测试
  vitest.config.ts             # Vitest 测试配置
 ```
 
+## 会话存储
+
+会话历史由 `packages/session-sqlite` 持久化，默认数据库路径为 `.agent-sessions/sessions.db`。也可以通过 `SESSION_DB_PATH` 环境变量覆盖路径。数据层支持：
+
+- 会话：会话元数据、父子会话和当前工作目录。
+- 条目：用户、助手、工具和系统消息，支持泳道与分支。
+- 记录与统计：运行记录、token 消耗、成本等统计信息。
+- 事实与租约：供长任务复用的事实表，以及并发写入保护租约。
+
 ## 快速开始
 
 1. 安装依赖（建议 Node.js 20+，并使用 pnpm）。
-2. 将 `.env.example` 复制为 `.env`，配置 `OPENAI_API_KEY`。
+2. 将 `.env.example` 复制为 `.env.local`（或 `.env`），配置 `OPENAI_API_KEY` 与 `OPENAI_MODEL`。
 3. 启动 CLI，入口为 `source/app.tsx`。
 
 ```bash
-cp .env.example .env
+cp .env.example .env.local
 pnpm install
 pnpm dev
 ```
 
+进入 CLI 后可以直接输入自然语言任务。CLI 默认按当前模式执行：`PLAN` 模式先生成计划，`BUILD` 模式直接参与文件读写和命令执行。计划生成后可用 Enter 确认执行，也可以继续补充修改意见。
+
 ## 环境变量
 
 | 变量 | 说明 |
@@ -88,6 +106,27 @@ pnpm dev
 | `OPENAI_API_BASE_URL` | 可选，自定义 OpenAI 兼容 base URL。 |
 | `OPENAI_MODEL` | 必填，模型名称，无默认值；未配置时 CLI 会提示。 |
 | `AGENT_DESKTOP_DIR` | 可选，覆盖桌面目录路径，便于测试或自定义工作环境。 |
+| `SESSION_DB_PATH` | 可选，SQLite 会话库文件路径，默认 `.agent-sessions/sessions.db`。 |
+| `CALL_CODE_WEB_DATA` | 可选，CLI 内 `/export` 的输出路径，默认 `packages/client/public/data.json`。 |
+
+## CLI 命令与快捷键
+
+```text
+/help      查看命令与快捷键
+/history   打开最近对话和相关页面选择
+/pages     打开相关页面选择
+/memory    查看 memory 概览
+/status    查看当前 CLI 状态
+/export    导出会话数据到 GitHub Pages 客户端
+/mode      查看当前模式和阶段
+/plan      切换到 PLAN 模式
+/build     切换到 BUILD 模式
+/clear     清空当前聊天窗口
+/home      返回首页并保留当前会话
+/exit      结束当前会话并返回首页
+```
+
+快捷键：`Tab` 切换模式，`Ctrl+H` 打开历史选择，`Esc` 返回首页或退出选择，`Ctrl+C` 退出程序。
 
 ## 常用命令
 
@@ -98,10 +137,16 @@ pnpm dev
 pnpm dev
 
 # 类型检查
-pnpm exec tsc -p tsconfig.json --noEmit
+pnpm typecheck
+
+# 类型检查（session-sqlite）
+pnpm exec tsc -p packages/session-sqlite/tsconfig.json --noEmit
+
+# 类型检查客户端
+pnpm typecheck:client
 
-# 运行测试
-pnpm exec vitest run --reporter verbose
+# 运行全部测试（推荐）
+pnpm test
 
 # 构建 agent-core
 pnpm run build:agent-core