wctx

编码代理的工作空间上下文。

你的系统横跨多个仓库。你的代理的上下文也应该如此。

wctx capture --summary "what this session figured out"   # at the end of a session
wctx search  "has anyone looked at this?"                # from any other repo, later

Session in Repo A
        ↓
discovers behavior in Repo B
        ↓
wctx
        ↓
fresh session in Repo B retrieves it

编码代理会话的作用域限定在一个仓库内，因为文件是在那里被编辑的。但被调查的系统并非如此。因此，在你的 UI 仓库中进行的一个会话发现 bug 实际上在你的 SDK 中——而当你一周后在 SDK 中打开一个新会话时，那个知识就消失了。

wctx 将已完成的代理会话转化为结构化的、有证据支持的工程上下文，并通过 MCP 将其提供给未来的会话。本地优先：无需云账户、无需嵌入、无需上传对话记录。

两分钟演示

pnpm install
pnpm demo

无需 API 密钥，无需网络。它构建三个合成仓库，从一个仓库导入一个已完成的会话，然后从另一个仓库提出一个自然语言问题：

$ wctx search "Has the selfie session expiration issue already been investigated?" --repo websdk-demo

  3 result(s) · 4 candidates · 14ms · searched websdk-demo plus 2 related repositories

  1. WebSDK uploadSessionImage does not retry after session expiration  [finding]
     from websdk-demo · session ses_8d3fb1a5 · commit 45a4cab · confidence 0.87
     · matches the query text
     · same repository
     · matches symbol uploadSessionImage

  3. Verify UI delegates selfie upload to the WebSDK  [finding]
     from verify-ui-demo · session ses_8d3fb1a5 · commit b041200 · confidence 0.95
     · matches the query text
     · verify-ui-demo uses websdk-demo (direct consumer)
     · high stated confidence (0.95)

然后 SDK 文件发生变化，证据变得不可信：

$ wctx evidence verify ev_9ae81278
  before: current — The repository is still at the source commit b60a991; nothing has changed.
  after:  stale   — All 1 referenced file(s) changed in b60a991..1ceeaa4. Re-read the code
                    before relying on this.

完整演练：docs/demo.md。

Related MCP server: obsmcp

安装

需要 Node 22+ 和 git。

pnpm install
pnpm build
npm link        # optional: puts `wctx` on your PATH

wctx init       # creates ~/.wctx
wctx doctor     # checks database, git, adapters, and prints MCP setup hints

MCP 设置

claude mcp add wctx -- wctx mcp

或者，对于 Codex 和其他 MCP 客户端：

{ "mcpServers": { "wctx": { "command": "wctx", "args": ["mcp"] } } }

七个工具，按渐进式披露排序，以便在上下文窗口中保持经济性：

wctx mcp-info 打印接口和客户端配置片段。

记录会话学到的内容

一个命令，在会话结束时执行。它会在一个步骤中导入会话（如果需要）并记录证据，默认使用你正在运行的会话：

wctx capture --summary "Traced the upload failure into the SDK" \
  --finding "SDK swallows the 419 :: uploadSessionImage returns it as terminal, no retry" \
  --repo my-sdk \
  --file "src/session/upload.ts#uploadSessionImage"

或者直接让你的代理去做——"记录我们学到的内容"——它会使用自己的会话 ID 调用 finalize_session。它永远不需要知道内部 ID，并且在一个会话中重复调用会累积证据，而不是重复会话。

使其主动化

只有当有东西告诉代理时，它才会这样做，而最有力的地方是项目的代理文件——这些文件在每次请求时都会被读取：

wctx instructions          # print the guidance
wctx instructions --write   # install it into CLAUDE.md / AGENTS.md (idempotent)

指南涵盖了何时搜索（在调查任何非平凡问题之前）、何时记录（根本原因、带有理由的决策、来之不易的约束、未解决的问题、意外情况），以及不记录什么。这就是一个你记得使用的工具和一个自动积累的工具之间的区别。

如果完全没有提供摘要，wctx capture 会从会话记录的工具活动中推导出一个事实性摘要——文件数量、命令、错误、更改的文件。故意平淡：从工具调用中编造一个叙述正是这个项目拒绝产生的自信的废话。

核心概念

工作空间 — 仓库之上的逻辑产品。上下文边界。仓库仍然是编辑边界；这里没有任何东西会扩大代理的写入范围。

仓库 — 一个已注册的 git 检出，通过其真实路径标识，因此同一个仓库不能通过符号链接或子目录注册两次。它可以属于多个工作空间。

关系 — 一个声明的、有方向的、类型化的边（uses、depends_on、calls、imports、consumes_api、provides_api、shares_schema_with、related）。遍历沿两个方向跟随边，因为如果 verify-ui 使用 websdk，那么 websdk 中的会话仍然想要 verify-ui 学到的东西。

会话 — 来自 Xirp、Claude Code 或通用 JSONL 的规范化编码代理会话，包含其 cwd、分支、提交、消息和工具活动。

证据 — 一个发现、决策、变更、未解决问题、已知问题、架构说明或约束，附加到它关于的仓库（通常不是会话运行的仓库），包含它涉及的文件和符号以及它成立时的提交。

新鲜度 — 基于 git 的判断，关于引用的文件自该提交以来是否已更改：current、possibly_stale、stale 或 unknown。

架构

Xirp · Claude Code · Codex · generic JSONL
                  ↓
          session adapters              ← the only code that knows a vendor format
                  ↓
        NormalizedSession
           ↓            ↓
  transcript copy   deterministic extraction (files, commands, errors — no LLM)
                        ↓
              structured evidence (findings, decisions, questions)
                        ↓
              workspace catalog · SQLite + FTS5 + git
                        ↓
              CLI  ·  MCP  ·  web UI          ← one service layer, no duplicated logic

详细信息，以及每个边界背后的理由：docs/architecture.md。

Xirp 集成状态

Xirp 结果证明暴露了一个真实的、有文档记录的读取路径，因此适配器是真实的，而不是一个存根。

适配器固定了两个架构字符串，并在遇到未知版本时大声失败，而不是猜测。完整的证据，包括仍未验证的内容以及如何重现：docs/research/xirp.md。

安全性

没有任何东西离开你的机器。没有云、没有遥测、没有嵌入 API、没有对话记录上传；整个依赖列表是 @modelcontextprotocol/server、better-sqlite3、commander 和 zod。

• 对话记录被复制到你的数据目录中（Claude Code 会在 30 天后删除自己的副本），同时还有一个经过编辑的副本——并且只有经过编辑的副本才会被提供。

• 编辑涵盖私钥、JWT、授权头、AWS/GitHub/Slack/OpenAI/Google 令牌、带凭据的 URL 和秘密赋值。这是尽力而为的模式匹配，并不保证对话记录可以安全共享。

• 返回给代理的证据被标记为历史性的、不可信的数据，并且类似指令的行（"忽略所有先前的指令"）被中和。缓解措施，而非免疫。

• 每个 git 调用都使用参数数组，而不是 shell 字符串。FTS5 查询是构造的，而不是插值的。

• 对话记录删除和证据删除是独立操作。

详细信息：docs/security.md。

与现有工具的比较

能力声明来自每个项目自己的 README，检查于 2026-08-13。这里没有断言另一个项目不能做某事。

包含每个项目的内存边界、捕获机制以及被重用为想法的内容的完整调查：docs/research/competitive-landscape.md。

评估

在一个合成的 15 查询、28 项语料库（pnpm eval）上，相关的先前会话出现在15 个查询中的 15 个的前五名中，并在15 个中的 11 个中排名第一，中位本地检索延迟为1.6 毫秒。将工作空间拓扑添加到纯 FTS5 中，在此语料库上命中率保持不变，但将 MRR 从 0.839 提高到 0.867，使仓库归属精确（0.93 → 1.00），并消除了来自不相关仓库的结果（每个查询 0.20 → 0.00）。

该语料库很小，是合成的，并且由编写查询的同一个人编写。这对阅读数字意味着什么在 docs/evaluation.md 中有详细说明。

局限性

完整的诚实列表：KNOWN_LIMITATIONS.md。其中最重要的三条：

• 检索是关键词形状的。 FTS5 匹配的是词元。一个完全改写且无词汇重叠的查询可能会遗漏；结构提升只能部分弥补。

• 新鲜度不等于验证。 它回答的是“引用的文件是否发生了变化？”，而从不回答“这个声明是否仍然成立”。未触及文件中的行为变化是不可见的。

• 关系是声明的，而非推断的。 未声明的关系对排序是不可见的。

路线图

按对核心循环改进程度排序：

1. 通过一个 harness stop 钩子实现自动会话终结（目前为手动）。

2. 跨版本以及 codex / gemini harness 的 Xirp 适配器加固。

3. 冲突检测和替代建议——模式支持两者，但尚无内容填充。

4. 在现有 CatalogProvider 接缝后导入 Backstage / Portal 的 catalog-info.yaml。

5. 一个更难的评估语料库，包含近似重复的发现，以测试拓扑是否有助于发现而不仅仅是排序。

贡献

参见 CONTRIBUTING.md。必须通过 pnpm typecheck && pnpm lint && pnpm test，并且 pnpm demo 必须能在无凭据的干净克隆中工作。

归属与非附属声明

wctx 是一个独立的开源实验，灵感来源于 Xirp、Spotify Portal、Backstage 和 MCP 的公开想法。

它与 Spotify 无关联，也未获得 Spotify 认可。

比较表中的任何项目均未复制其源代码。Backstage 的 Component/System 区分仅作为设计灵感，而非运行时依赖，且无需运行 Backstage 实例。

许可证

MIT。参见 LICENSE。