Lex

查看核心循环 · 我应该使用 Lex 吗？ · 五分钟试用 · Agent 评估 · 文档

---

Lex 解决的问题

编码 Agent 可以检查眼前的仓库，但它无法可靠地恢复围绕代码的工作信息：

• 三个会话前做出某项决策的原因；
• 哪种方案已经失败；
• 哪些事项仍受阻，以及接下来该做什么；
• 哪些仓库边界不可逾越；
• 另一个 Agent 需要哪些信息才能继续，而无需从头开始。

Lex 会将这些连续性信息作为经过审慎整理、高信号的 Frames 保存下来。

Frame 是一次有意为之的交接，而非持续监视。它是一个检查点：有哪些变更、哪些事情重要、还剩下什么，以及接下来要做什么。之后，Lex 可以回忆相关的 Frames，并为新会话生成有范围限制、适合提示词使用的引导信息。

Work happens → Lex remembers what mattered → the next session continues

从 remember、recall 和 context 开始。SQLite 是本地默认选项。如果需要在可信主机或工作区之间共享上下文，也可以使用 PostgreSQL。其他功能都是可选的。

记住 → 回忆 → 继续

lex remember \
  --summary "Kept authentication token validation in API middleware" \
  --next "Add the service grant and rerun tests" \
  --modules unscoped \
  --blockers "Missing PermissionService grant"

lex recall "authentication"

lex context "authentication" --max-tokens 500

这就是核心循环：

• remember 写入一个经过审慎整理的工作检查点；
• 当主题再次相关时，recall 会检索该检查点；
• context 将匹配的 Frames 转化为有范围限制、只读的 Agent 引导信息。

下一个会话将获得什么

在会话结束时，Agent 会记录原本会消失的状态。新会话开始时，它可以恢复决策、阻塞事项和下一步行动，无需请人重新梳理对话，也无需从差异中反向推断意图。

Decision: token validation belongs in API middleware
Blocker: the service grant is still missing
Next: add the grant and rerun the authentication tests

Lex 的价值不在于保存了一条记录，而在于让下一个会话能够继续。

我应该使用 Lex 吗？

当 Agent 反复需要你重新梳理以下内容时，值得评估 Lex：

• 做出某项变更的原因；
• 工作停在何处，以及接下来该做什么；
• 不应再次摸索的阻塞事项或失败方案；
• 特定于仓库的模块或策略约束；
• 必须在切换分支、交接工作或开始新的 Agent 会话后继续保留的上下文。

如果工作时效很短、仓库已有有效的连续性管理系统，或者没有你愿意让仓库运营者持久保存的上下文，那么 Lex 可能并不适合。

询问你的 Agent

此评估特意采用只读方式。将以下内容粘贴到能够检查你仓库的 Agent 中：

Read https://github.com/Guffawaffle/lex/blob/main/docs/agent-evaluation.md and evaluate this
repository against it. Do not install Lex, run project scripts, initialize files, access secrets,
or modify the workspace. Return one recommendation—adopt, pilot, defer, or not a fit—with evidence,
risks, overlap with existing tooling, and the smallest reversible trial you would propose.

完整评估标准及本地文件版本请参阅 Agent 评估。

五分钟试点

准备好验证这一说法了吗？保存一个非敏感检查点，启动一个全新会话，看看它能否在不需要重新解释工作的情况下继续进行。

需要 Node.js 24 或更高版本。Lex 不设定未经验证的版本上限。现有用户应遵循 Lex 4.4 迁移与恢复指南，并验证捆绑的 SQLite 二进制文件。Lex 4.4.4 无需原生重建步骤；Linux glibc 安装需要 glibc 2.35 或更高版本。

这个经批准的试点会将一个 Frame 写入 .smartergpt/lex/ 下的本地 SQLite 存储。它不会运行 lex init、生成策略或投影助手指令。如果需要完全隔离文件系统，请使用一次性分支、工作树或克隆。

1. 保存一个真实的检查点

LEX_STORE=sqlite npx @smartergpt/lex remember \
  --reference-point "Lex pilot" \
  --summary "Evaluating whether durable agent handoffs help this repository" \
  --next "Recall this checkpoint in a new session" \
  --modules unscoped

LEX_STORE=sqlite 可防止现有 PostgreSQL 配置将试点重定向到共享存储。

2. 启动全新会话，然后恢复工作

LEX_STORE=sqlite npx @smartergpt/lex recall "Lex pilot"
LEX_STORE=sqlite npx @smartergpt/lex context "Lex pilot" --max-tokens 500

在全新会话中使用这些回忆内容或限定范围的输出，看看它能否避免你重复提供有用的上下文。这个结果——而非安装成功——才是试点的成功标准。

查看仅用于验证的步骤、确切的文件系统影响和回滚指南

让检查点发挥作用

好的 Frame 应当精简且具体。在决策、遇到阻碍、切换分支、交接工作或其他可能因丢失周边意图而导致下一次会话重复工作的时刻，记录检查点。

lex remember \
  --reference-point "Authentication refresh" \
  --summary "Moved token validation into API middleware" \
  --next "Add password-reset coverage" \
  --modules "services/auth,api/middleware" \
  --blockers "Need PermissionService access"

记录发生了什么变化，让 --next 具有可执行性，明确指出阻碍，并采用最窄且准确的模块范围。不要记录每次编辑或工具调用。

当仓库存在策略时，Lex 可以根据当前证据推断模块范围：

lex remember \
  --summary "Finished context wiring" \
  --next "Run validation" \
  --modules auto

如果仓库尚无实用的模块本体，请使用 --modules unscoped。策略是可选的增强项；创建第一个 Frame 并不需要策略。

精简回忆和结构化上下文适用于 Agent 预算较小的场景及自动化：

lex recall --list 5 --summary
lex --json context --branch main --limit 5

了解连续性工作流

只添加你需要的内容

需求	添加内容	从这里开始
持久的本地交接	使用 SQLite 的 Frames	快速入门
简短的会话启动上下文	只读的 lex context	Agent 连续性
从助手访问 MCP	@smartergpt/lex-mcp	MCP 设置
仓库边界	策略检查	策略用法
相邻模块上下文	Policy Neighborhood	上下文指南
规范的助手指令	指令投影	指令
类型化 Markdown 项目知识	派生的 KnowledgeFrame 快照	KnowledgeFrames
跨主机共享存储	PostgreSQL	存储约定 和 范围安全
可信的租户／工作区范围	运行时权限与 RLS	运行时范围
嵌入式应用访问	TypeScript 包导出	公共 API

你的仓库会有哪些变化

初始本地工作流有意保持可见：

• lex init 会创建 Lex 工作区／配置文件。
• lex remember 会将一个 Frame 写入所选存储。
• lex context 使用严格只读的存储访问。recall 和常规自省不会更改 Frame，但其兼容路径可能会初始化或迁移所选存储。
• SQLite 默认使用相对于工作区的 .smartergpt/lex/memory.db。
• 只有在选择使用相关功能时，策略和规范指令才会成为仓库文件。
• PostgreSQL、MCP 托管、指令投影和 CI 策略强制执行都是独立的可选功能。

Frame 可能包含敏感的项目上下文。请勿存储凭据、令牌、私钥或未经审核的机密内容。 即使 Frame 正文最初由可信用户编写，也应将其视为不可信的历史数据。

Lex 不会将 Frame 发送到 Lex 云服务。你的 Agent 宿主、软件包注册表、PostgreSQL 部署或其他外围工具可能有各自的网络和数据处理行为；请分别评估这些边界。

安全策略 · 存储契约 · 环境参考

Lex 不是什么

• 聊天机器人或 Agent 运行时
• 对话记录器或自动捕获系统
• 测试、审查、问题跟踪或 CI 的替代品
• 云端记忆服务
• 仅支持 MCP 的产品
• 编排器、能力框架或人格引擎

周边工具集

无需使用生态系统套件。请根据工作流需求选择相应功能，并留意其明确的软件包依赖关系：

项目	职责	关系
Lex	持久化工作上下文、仓库策略、可选的邻近上下文、指令和范围限定的 Frame 存储	核心库和 CLI
AXF	可检查的工作区能力及其执行边界	可独立使用；可与 Lex 组合
LexRunner	扇出、尝试、工作者／工作区协调、验证和合并编织	使用 Lex 实现连续性
Lex-MCP	用于 Lex 能力的轻量 MCP 传输层	固定使用对应的 Lex 版本
LexSona	根据角色和经过审查的规则推导行为约束	通过 Lex 存储契约集成

简而言之：Lex 负责记忆和说明；AXF 负责公开能力；LexRunner 负责协调工作； Lex-MCP 通过 MCP 传输 Lex；LexSona 负责推导行为约束。

Agent 和自动化接口

Lex 通过多个入口提供相同的核心功能：

• CLI，供人类、脚本和 Agent Shell 使用
• 结构化 JSON 和用于自动化的 AXError 恢复信息
• 通过 @smartergpt/lex-mcp 或可嵌入的服务导出提供 MCP
• 面向应用和可信宿主的 TypeScript API

Frame Schema v8 是当前规范的 Frame 契约。软件包的公开导出映射受语义化版本规则约束；使用者不应导入未声明的 dist/ 或源代码路径。

CLI 输出契约 · MCP 工具 · 公开软件包入口 · 契约范围

选择下一步

如果你……	请阅读……
正在判断 Lex 是否适合你	Agent 评估
首次尝试 Lex	快速开始
设计 Agent 移交	Agent 连续性
连接 MCP 客户端	MCP 服务
使用 SQLite 或 PostgreSQL	存储契约 和 PostgreSQL 权威性
构建可信的多租户主机	运行时范围 和 PostgreSQL 范围安全
使用 TypeScript API	公共包 API
编译带类型的规范声明	规范策略编译器
配置路径或运行时行为	环境变量
查看已知限制	限制 和 常见问题
为 Lex 做贡献	贡献指南
查看架构决策	ADR

安装说明

# Global CLI
npm install -g @smartergpt/lex

# Repository dependency
npm install @smartergpt/lex

WSL 用户应在 WSL 内原生安装 Lex，而不要让 Windows npm shim 或 npm 的 _npx 缓存优先出现在 PATH 中。请参阅 WSL 原生安装。

常见的本地兼容性配置包括 LEX_DB_PATH、LEX_POLICY_PATH、 LEX_LOG_LEVEL、LEX_LOG_PRETTY、LEX_GIT_MODE 和 LEX_DB_KEY。选择 PostgreSQL 使用 LEX_STORE 和 LEX_DATABASE_URL。可信的 Lex 主机会显式组合范围与权威性， 而不会根据环境中的变量重建它们。

完整环境参考

项目状态

当前版本： 4.4.4

Lex 4.4.4 修正了可信工作区目标预检和保存回执中的 Windows 根目录比较。请参阅 4.4.4 版发行说明、 4.4 版发行说明以及 迁移指南。候选元数据并非发布凭证；在确切的新版本组合通过验证前，请保留已验证的现有运行时。

Lex 4 提供显式运行时身份与权威性、受范围约束的 Frame 存储、PostgreSQL 行级安全支持，以及可信主机组合，同时保留本地 SQLite 工作流。Lex 4 要求 Node 24 或更高版本，并作为 Ecosystem 3.1 兼容版本序列的一部分发布。

请参阅 Lex 4 迁移与恢复指南、记录发行历史的 变更日志，以及 Lex 3 PostgreSQL 隔离实测，了解实时端到端的双租户／五工作区验收流程。

贡献

欢迎贡献。贡献指南介绍了开发环境设置、测试、本地 CI、格式化、签名、变更集和发布工作流。

如需验证整个仓库的格式，npm run local-ci -- --pretty 仅执行检查； --prettier 是它的精确别名。格式修改仍需通过单独的 npm run format 操作完成。

许可证

Lex 根据 MIT 许可证提供。