# Lattice — AI Agent 双室记忆系统

> **解决 AI Agent 的"金鱼记忆"问题**

Lattice 是一个 **双室记忆系统**，让 AI Agent 能够：
- **记住** 你的偏好、约定、决策
- **进化** 自动从对话中提取规则
- **搜索** 历史对话找到相关上下文

```
┌─────────────────────────────────────────────────────────┐
│  System 1 (Instinct)     │  System 2 (Memory)          │
│  ─────────────────────   │  ─────────────────────       │
│  始终加载的规则           │  可搜索的日志                │
│  0ms 延迟                │  ~100ms 延迟                 │
│  Markdown 文件           │  SQLite + 向量搜索           │
│  "偏好 TDD"              │  "上周我们修复了 auth 问题"  │
└─────────────────────────────────────────────────────────┘
                    ▲
                    │ Compiler (LLM)
                    │ 从日志中提取模式，生成规则
                    │
            ┌───────┴───────┐
            │   store.db    │
            │  (对话日志)    │
            └───────────────┘
```

## 安装

```bash
# 从 GitHub 安装
pip install git+https://github.com/tefx/lattice.git

# 或克隆后本地安装
git clone https://github.com/tefx/lattice.git
cd lattice
pip install -e .
```

## 快速开始

### 1. 导入第一条数据

```bash
lattice ingest
```

这将自动初始化项目：
- 创建 `./.lattice/` — 项目级记忆目录
- 创建 `~/.config/lattice/` — 全局配置目录（如需要）

### 2. 配置 LLM

编辑 `~/.config/lattice/config.toml`：

```toml
[compiler]
# 推荐：GPT-5 Mini（性价比最佳）
model = "openrouter/openai/gpt-5-mini"
api_key_env = "OPENROUTER_API_KEY"

# 或使用 opencode CLI（零配置）
# model = "cli:opencode:openrouter/openai/gpt-5-mini"

[thresholds]
warn_tokens = 3000
alert_tokens = 5000

[safety]
auto_apply = true
backup_keep = 10
```

设置环境变量：
```bash
export OPENROUTER_API_KEY="sk-or-..."
```

### 3. 数据捕获

**方式 A：OpenCode Plugin（推荐）**

```bash
# 安装插件（TypeScript，单文件）
mkdir -p ~/.config/opencode/plugins
curl -o ~/.config/opencode/plugins/lattice-capture.ts \
  https://raw.githubusercontent.com/tefx/lattice/main/plugins/opencode-lattice/index.ts

# 或克隆并复制：
git clone https://github.com/tefx/lattice.git
mkdir -p ~/.config/opencode/plugins
cp lattice/plugins/opencode-lattice/index.ts ~/.config/opencode/plugins/lattice-capture.ts

# 重启 opencode
opencode
```

OpenCode 使用 Bun 运行时，原生支持 TypeScript — 无需构建步骤。

**替代方案：从 npm 安装（发布后）**

```json
// ~/.config/opencode/opencode.json
{
  "plugin": ["opencode-lattice"]
}
```

**方式 B：MCP Server**

```bash
# 启动 MCP server
lattice serve

# 在 Claude Code / opencode 中配置 MCP
```

**方式 C：Python SDK**

```python
import lattice

client = lattice.Client()

# 记录对话
client.log_turn(
    user="修复 auth bug",
    assistant="我更新了 middleware...",
)

# 搜索历史
results = client.search("auth bug", limit=5)

# 获取规则
instincts = client.get_instincts()
```

### 4. 进化规则

```bash
# 增量进化（只处理新 session）
lattice evolve

# 查看状态
lattice status

# 应用/拒绝提案
lattice apply <proposal>
lattice revert
```

## CLI 命令

```bash
# 数据导入（首次使用自动初始化）
lattice ingest                  # 从 stdin 导入消息

# 进化
lattice evolve                  # 项目级进化
lattice evolve --global         # 全局进化（跨项目模式）
lattice status                  # 查看状态

# 搜索
lattice search "关键词"         # 搜索项目记忆
lattice search --global "关键词" # 搜索全局记忆

# 规则管理
lattice apply <proposal>        # 应用提案
lattice revert                  # 回滚

# MCP
lattice serve                   # 启动 MCP server

# 配置
lattice config init --global    # 创建全局 config.toml
lattice config show --global    # 显示当前配置
```

## 配置

Lattice 会创建一个包含所有选项文档的配置文件。

### 创建配置

```bash
# 创建全局配置（包含所有选项文档）
lattice config init --global

# 或强制覆盖现有配置
lattice config init --global --force
```

全局配置会在首次使用时自动创建。

### 配置文件位置

```
~/.config/lattice/config.toml   # 全局配置
```

### 快速设置

```bash
# 1. 导入第一条数据（自动创建配置）
lattice ingest

# 2. 保存 API Key
lattice auth login openai
# API Key for openai: ********
# ✓ Saved API key for openai
#   Key will be used automatically (no config.toml changes needed)

# 3. 编辑模型配置（可选）
vim ~/.config/lattice/config.toml
# 修改 model = "openai/gpt-5-mini" 为你喜欢的模型

# 4. 开始使用
lattice evolve
```

## Shell 补全

Lattice 支持 **bash**、**zsh**、**fish** 和 **PowerShell** 的 shell 补全。

### 安装补全

```bash
# 自动检测 shell 并安装
lattice completion --install

# 或显式指定 shell
lattice completion --shell bash --install
lattice completion --shell zsh --install
lattice completion --shell fish --install
lattice completion --shell powershell --install
```

安装后，重启终端或 source 补全文件：

```bash
# Bash
source ~/.bash_completions/lattice.sh

# Zsh（添加到 ~/.zshrc）
fpath+=~/.zfunc
autoload -U compinit && compinit
```

### 显示补全脚本

查看或手动安装补全脚本：

```bash
lattice completion --shell zsh
lattice completion --shell bash
lattice completion --shell fish
```

## API Key 配置

Lattice 支持灵活的 API Key 配置，支持多种来源和优先级解析。

### 快速设置（推荐）

只需运行 `lattice auth login` 即可：

```bash
lattice auth login openai
# API Key for openai: ********
# ✓ Saved API key for openai
#   Key will be used automatically (no config.toml changes needed)
```

完成！无需编辑 config.toml。Key 被安全存储并自动使用。

### 优先级顺序

Key 按以下顺序解析（从高到低）：

1. **配置 `api_key`/`api_key_env`** - config.toml 中的显式配置
2. **Auth 存储** - `~/.config/lattice/auth.json`（自动回退）
3. **环境变量** - 标准环境变量（如 `OPENAI_API_KEY`）
4. **LiteLLM 默认值** - LiteLLM 内置的 key 检测

**关键点**：如果你使用 `lattice auth login`，就不需要在 config.toml 配置任何东西。

### 何时使用 config.toml

只有在以下情况才需要在 config.toml 添加 `api_key` 或 `api_key_env`：

1. **覆盖** auth 存储中特定模型的 key
2. 为不同 provider **使用不同的 key**
3. 在 CI/CD 中**使用环境变量**

```toml
[compiler]
model = "openai/gpt-4"
# 可选：覆盖 auth 存储
# api_key = "{env:MY_CUSTOM_KEY}"
# api_key_env = "MY_CUSTOM_KEY"
```

### 变量语法

在配置中使用以下变量格式（仅高级场景需要）：

| 语法 | 描述 | 示例 |
|------|------|------|
| `{env:VAR}` | 从环境变量读取 | `{env:OPENAI_API_KEY}` |
| `{file:/path}` | 从文件读取 | `{file:~/.secrets/openai_key}` |
| `{auth:provider}` | 从 auth 存储读取 | `{auth:openai}` |
| 直接 key | 明文（不推荐） | `sk-proj-...` |

### Auth CLI 命令

安全管理你的 API Key：

```bash
# 保存 API Key（带掩码的安全提示）
lattice auth login openai

# 或通过命令行提供（会显示在历史中，较不安全）
lattice auth login openai --key sk-proj-...

# 列出已保存的 provider（key 会被隐藏）
lattice auth list

# 测试 API Key
lattice auth test openai

# 删除 API Key
lattice auth logout openai
```

### 安全最佳实践

1. **使用 auth 存储** - Key 以 `chmod 0o600` 权限存储
2. **避免 `--key` 参数** - 它会显示在 shell 历史中；使用交互式提示
3. **避免配置中的直接 key** - 永远不要在配置文件中硬编码 key
4. **使用环境变量** - 适用于 CI/CD 流水线

### 文件位置

Auth Key 存储在：
```
~/.config/lattice/auth.json
```

文件以 `0o600` 权限创建（仅所有者可读写）。

## 完整使用流程

本节介绍从初始化到观察记忆效果的典型使用周期。

### 第 1 周：设置与数据收集

```bash
# 第 1 天：设置
cd your-project
lattice ingest                  # 首次使用自动初始化

# 配置 Compiler
cat > ~/.config/lattice/config.toml << 'EOF'
[compiler]
model = "openrouter/openai/gpt-5-mini"
api_key_env = "OPENROUTER_API_KEY"

[thresholds]
warn_tokens = 3000
alert_tokens = 5000

[safety]
auto_apply = true
backup_keep = 10
EOF

export OPENROUTER_API_KEY="sk-or-..."

# 验证设置
lattice status
# 输出：
# ── Sessions ─────────────────────
# Total: 0
# Pending evolution: 0
#
# ── Rules ───────────────────────
# rules/: 0 files, 0 tokens
```

```bash
# 第 1-7 天：正常使用 Agent
# OpenCode Plugin 自动捕获对话
# 或使用 MCP：lattice serve

# 检查数据收集
lattice status
# 输出：
# ── Sessions ─────────────────────
# Total: 23
# Pending evolution: 23
```

### 第 1-2 周：首次进化

```bash
# 运行 Compiler 提取模式
lattice evolve

# 输出：
# Processing 23 sessions...
# LLM response received.
# Proposals written to:
#   - drift/proposals/20260219_143052_prefer_explicit_imports.md
#   - drift/proposals/20260219_143052_use_result_types.md
#
# Applied 2 proposals.
# Updated last_evolved_at.

# 检查生成的规则
lattice status
# 输出：
# ── Sessions ─────────────────────
# Total: 23
# Pending evolution: 0
#
# ── Rules ───────────────────────
# rules/: 2 files, ~450 tokens
#
# ── Proposals ───────────────────
# Pending: 0

# 查看生成的规则
cat .lattice/rules/*.md
```

### 第 2-4 周：迭代与审查

```bash
# Sessions 随时间积累
lattice status
# ── Sessions ─────────────────────
# Total: 67
# Pending evolution: 15

# 再次运行进化（增量 - 只处理新 session）
lattice evolve

# 如果 auto_apply=false，手动审查并应用
lattice status
# ── Proposals ───────────────────
# Pending: 3 proposals

# 审查提案
cat .lattice/drift/proposals/20260225_091234_avoid_bare_except.md

# 应用
lattice apply drift/proposals/20260225_091234_avoid_bare_except.md

# 或拒绝（删除文件）
rm .lattice/drift/proposals/20260225_091234_avoid_bare_except.md

# 犯错了？回滚
lattice revert
# Restored from backup: .lattice/backups/rules_20260219_143052.tar.gz
```

### 第 1 月+：搜索与跨项目

```bash
# 搜索历史对话
lattice search "authentication bug"
# 输出：
# [1] ses_abc123 (user, 2026-02-15)
#     "I keep getting 401 errors on the API..."
# [2] ses_def456 (assistant, 2026-02-15)
#     "The JWT tokens were expiring. I added refresh logic..."

# 多项目后，运行全局进化
lattice evolve --global
# 扫描所有注册项目，找出跨项目模式
# ≥3 个项目重复出现的规则提升为全局规则

# 查看全局规则
lattice status --global
# ── Global Rules ─────────────────
# rules/: 3 files, ~600 tokens
```

### 效果衡量

| 信号 | 如何验证 |
| ---- | -------- |
| **数据收集** | `lattice status` 显示 session 数量增加 |
| **模式提取** | `lattice evolve` 在 ~10+ sessions 后生成提案 |
| **规则积累** | `rules/` 目录的 `.md` 文件增加 |
| **行为变化** | Agent 开始自动应用学到的偏好 |
| **搜索有用** | `lattice search "关键词"` 返回相关历史 |

### 关键文件监控

```bash
# Session 日志（System 2）
sqlite3 .lattice/store.db "SELECT COUNT(*) FROM logs;"

# 生成的规则（System 1）
ls -la .lattice/rules/

# 待处理提案
ls -la .lattice/drift/proposals/

# 进化追踪（审计日志）
ls -la .lattice/drift/traces/

# 备份
ls -la .lattice/backups/
```

## 目录结构

```
~/.config/lattice/          # 全局配置（XDG 规范）
├── config.toml             # LLM 设置
├── projects.toml           # 项目注册表
├── rules/                  # 全局规则
├── store/
│   └── global.db           # 跨项目证据
├── drift/
│   ├── proposals/          # 待处理的全局提案
│   └── traces/             # 全局 Compiler 审计日志
└── backups/                # 全局规则备份

./.lattice/                 # 项目级记忆
├── rules/                  # 项目规则（System 1）
├── store.db                # 对话日志（System 2）
├── drift/
│   ├── proposals/          # 待处理的提案
│   └── traces/             # Compiler 推理日志（审计）
└── backups/                # 规则备份（用于回滚）
```

## 核心概念

| 概念 | 说明 |
| ---- | ---- |
| **Instinct** | 始终加载的规则（偏好、约定、约束） |
| **Compiler** | LLM 进程，从日志中提取模式生成规则 |
| **Store** | 可搜索的对话日志归档 |
| **Promotion** | 项目规则提升为全局规则（≥3 个项目重复出现） |

## 安全

- **Local-First**：所有数据本地存储
- **Secret Sanitization**：自动过滤 API Key、密码等敏感信息
- **Backup**：每次 apply 自动备份，可 revert

## 文档

- [RFC-002: Bicameral Memory Architecture](docs/RFC-002-Lattice-Bicameral-Memory.md)
- [Architecture Guide](docs/ARCHITECTURE.md) — Core/Shell 分层、数据流、配置
- [API Reference](docs/api-reference.md) — Python SDK 使用
- [Session Compression RFC](docs/RFC-002-R1-Session-Compression.md) — Layer 0/1 压缩，提升 token 效率

## 许可证

AGPL-3.0-only