decisiontrail

decisiontrail

decisiontrail 是面向编码 Agent 的本地决策记忆。当 Agent 做出选择时——例如使用哪个数据库、缓存或发布节奏——decisiontrail 会将决策及其做出时所受的限制一并记录下来，这样后续会话就能找到先例，而不必从头重新决策；如果选择发生变化，也可以明确地修订。

所有内容都保存在本地：决策存储在你设备上的一个 JSON 文件中。无需账户或登录，也不会访问网络。记录可以是普通提交，也可以是经过验证的决策记录（包含约束、证据和答案）；先例搜索只会参考经过验证的记录。 旧决策绝不会原地编辑——修订会创建一条新记录，并将旧记录标记为已取代，同时建立双向关联。

此软件包是对「elen」MCP 服务本地功能的全新独立重建（包含其 12 个工具中的 10 个）。原服务的两个联网模式 Beta 工具 elen_incoming 和 elen_team_search 需要托管工作区、登录和 API 密钥，因此未包含在内。

安装

npx @reneturcios/decisiontrail elen_status

也可以运行容器镜像：

docker run -i ghcr.io/cloudcorprecords/decisiontrail

容器默认运行 MCP 服务（见下文）。传入 CLI 参数即可改为将其用作 CLI。如果运行容器，请在存储目录上挂载卷，以便持久保存决策。

决策存储位置

• 存储路径：环境变量 DECISIONTRAIL_DB 指定的路径；若未设置，默认使用 ~/.decisiontrail/decisions.json。
• 文件是一个 JSON 文档。文件不存在时会从空存储开始；写入采用原子操作（先写临时文件，再重命名），因此写入过程中发生崩溃也不会截断存储内容。
• DECISIONTRAIL_AGENT 和 DECISIONTRAIL_PROJECT 用于指定 elen_status 报告的命名空间；两者默认值均为 local。

决策 ID 按创建顺序递增：d-1、d-2……

CLI

同一个可执行文件支持两种用法。每个工具都是一个子命令，接收一个 JSON 参数（无需参数的工具可选）；结果以 JSON 格式输出。

# Check the namespace before committing
decisiontrail elen_status

# Commit a decision with its limits
decisiontrail elen_commit '{"text":"Use Postgres for sessions","constraints":["must be durable"],"domain":"storage"}'

# Record a validated decision
decisiontrail elen_log_decision '{"constraints":["latency under 100ms"],"evidence":["benchmark run 42"],"answer":"Adopt the in-process cache","domain":"performance"}'

# Before a new decision, ask for pointers; then search validated precedents
decisiontrail elen_suggest '{"query":"session storage"}'
decisiontrail elen_search_precedents '{"query":"session storage"}'

# Read one record in full, revise one, survey the store
decisiontrail elen_expand '{"id":"d-1"}'
decisiontrail elen_supersede '{"id":"d-1","text":"Use Redis for sessions with Postgres fallback"}'
decisiontrail elen_get_context
decisiontrail elen_get_competency
decisiontrail elen_consolidate

decisiontrail --version

退出代码：成功时为 0，域错误时为 1（例如决策 ID 未知——错误信息会注明该 ID），用法错误和参数无效时为 2。

MCP 服务

npx -y @reneturcios/decisiontrail mcp

MCP 客户端配置：

{
  "mcpServers": {
    "decisiontrail": {
      "command": "npx",
      "args": ["-y", "@reneturcios/decisiontrail", "mcp"]
    }
  }
}

工具

工具	输入	返回内容
elen_commit	text（必填）、constraints（字符串数组）、domain	新建的未经验证的决策记录。
elen_log_decision	constraints、evidence、answer（均必填）、text、domain	根据这些输入构建的经过验证的决策记录。
elen_expand	id（必填）	该决策 ID 对应的完整记录。
elen_suggest	query（必填）、limit（默认值为 5）	与查询匹配的先前决策的简要信息（id、文本的前 120 个字符、domain、validated、status），按匹配度从高到低排列。搜索所有记录。
elen_search_precedents	query（必填）、limit（默认值为 5）	与查询匹配的完整记录；仅搜索经过验证的记录。
elen_supersede	id、text（均必填）、constraints、domain	新的后继记录；旧记录会被标记为已取代，且两条记录会建立双向关联。
elen_get_context	—	按领域分组的活跃决策线索，包含各领域的计数和最新文本，以及总计。
elen_status	—	Agent、项目、数据库路径和计数（总数 / 活跃 / 已取代 / 已验证）。
elen_get_competency	—	各领域经过验证的记录数，以及所有记录中经过验证的占比（覆盖率）；仅根据经过验证的历史记录得出。
elen_consolidate	—	重复项对（领域相同且词元 Jaccard 相似度至少为 0.6）、这些重复项形成的聚类，以及过时候选项（超过 90 天的活跃记录）。不会更改任何内容。

匹配方式

elen_suggest 和 elen_search_precedents 根据查询与记录文本及约束之间不区分大小写的词元重叠度进行排序：分数为查询中出现在记录里的不同词元数量。没有重叠的记录会被省略；分数相同时，按时间倒序排列，最新的排在前面。

只有通过 elen_log_decision 创建的记录才算经过验证。已提交的决策即使后来被取代，其历史记录也会保留：supersedes / superseded_by 用于关联决策链，旧记录的状态会变为 superseded。

开发

npm install
npm run build   # tsc -> dist/
npm test        # node test runner over test/*.test.ts, temp dirs, no network
npm run dev     # run the CLI from source via tsx

许可证

MIT — 参见 LICENSE。