Code Repositories

A registered repository is a source boundary: the code the Agent may read and cite while writing knowledge. Registration pins the repository to one commit, so every citation points at code that will not shift underneath it. It does not decide what to write; that comes later, in the work-start report.

flowchart LR
  you["You name a local checkout"] --> agent["Agent resolves the path"]
  agent --> cli["CLI reads origin and HEAD"]
  cli --> reg["Registered source<br/>date/module @ commit"]
  reg --> plan["Planning and writing<br/>read this commit only"]

Ask the Agent

Name the checkout and the part of it the readers need. Plain language is enough:

Use ../payments-service as a code source. Readers need the refund flow;
skip the legacy admin module.

When your request already names exact local modules, the Agent does not ask you to repeat them or to supply remote URLs: it resolves each name to one local directory and lets the CLI read that checkout's Git root, origin and current commit. It asks only when a name is ambiguous, nothing matches, or picking a match would widen the scope you gave.

What gets recorded

The Agent registers the module with a command like this:

context source add repo 20261012 --module payments-service --local ../payments-service --configure

Option	Meaning
20261012	The capture batch date. Several repositories and documents can share one date.
--module	Required. The concrete repository or package name.
--local	Local checkout path; may point at a monorepo subdirectory.
--remote / --ref	Remote URL and pinned commit. Inferred from the local origin and HEAD when omitted.
--configure	Also selects the source in a simple src/index.ts. It never captures anything.

The source is addressed as date/module, for example 20261012/payments-service. That name appears in source references; stable code knowledge paths use the module name without the date. Code sources need no capture phase: the Agent reads the checkout at the pinned commit.

Monorepos: pick packages, not the whole tree

Context never widens a boundary from the current directory, package names or Git remotes. When a monorepo has several package boundaries, the Agent shows their paths and asks which ones should become sources. Point --local at each chosen package.

Filtering files inside a source cannot select a monorepo package, so choose the packages explicitly. Discuss obsolete or unrelated areas before indexing them — unnecessary code costs reading time and tokens — but do not drop a directory merely because its name looks old.

How the code is read

Parsing is a detail of the selected Indexer, not something you configure per repository. The Indexer inspects languages, manifests, entries, routes and contracts, then uses the smallest parser set that answers the reader's questions. Community parsers cover TypeScript/JavaScript, Go, Rush monorepos, Thrift, Protobuf, Markdown/MDX, API contracts, stylesheets and SQL schemas. See Code Extraction for how parser facts become pages.

Checkouts on another machine

Git stores only the recovery recipe for a repository source: remote, pinned commit and module paths. It does not store the checkout. When a Context knowledge workspace is opened elsewhere and a task needs that code, the Agent offers three choices:

1. point it at an existing local checkout;
2. name a bounded directory it may scan for a matching checkout; or
3. allow Context to clone the registered repository into .tmp/repo/.

A recovery clone always uses the registered commit, so existing knowledge stays reproducible. In ordinary mode the Agent asks before cloning; it never scans an unspecified disk root or substitutes another branch or nearby repository.

When the code moves on

Registration keeps its commit until you decide otherwise. To bring knowledge up to a newer commit, ask for an update: the Agent prepares the new version, compares it with what existing pages cite, and asks which pages need changes. The processed baseline advances only after the selected revisions are approved and built. See Updating Knowledge.

代码仓库

已登记的仓库是一个来源边界：Agent 在编写知识时可以阅读和引用的代码。登记会把仓库固定到一个 commit，因此每条引用指向的代码都不会在其下发生变动。登记并不决定要写什么；那是之后在开工报告中决定的。

flowchart LR
  you["你指定一个本地检出"] --> agent["Agent 解析路径"]
  agent --> cli["CLI 读取 origin 和 HEAD"]
  cli --> reg["已登记的来源<br/>date/module @ commit"]
  reg --> plan["规划和写作<br/>只读取该 commit"]

告诉 Agent

说明检出目录以及读者需要其中的哪一部分，用自然语言即可：

Use ../payments-service as a code source. Readers need the refund flow;
skip the legacy admin module.

如果你的请求已经点名了确切的本地模块，Agent 不会让你重复，也不会要求你提供远程 URL：它会把每个名称解析到一个本地目录，并让 CLI 读取该检出的 Git 根目录、origin 和当前 commit。只有当名称有歧义、没有匹配项，或选择某个匹配项会扩大你给定的范围时，它才会询问。

记录了什么

Agent 会用类似下面的命令登记模块：

context source add repo 20261012 --module payments-service --local ../payments-service --configure

选项	含义
20261012	采集批次日期。多个仓库和文档可以共用同一个日期。
--module	必填。具体的仓库或包名。
--local	本地检出路径；可以指向 monorepo 的子目录。
--remote / --ref	远程 URL 和固定的 commit。省略时从本地 origin 和 HEAD 推断。
--configure	同时在简单的 src/index.ts 中选中该来源。它从不执行任何采集。

来源以 date/module 的形式寻址，例如 20261012/payments-service。这个名称会出现在来源引用中；稳定的代码知识路径使用不带日期的模块名。代码来源不需要采集阶段：Agent 直接读取固定 commit 下的检出。

Monorepo：选择包，而不是整棵树

Context 从不依据当前目录、包名或 Git 远程来扩大边界。当 monorepo 中有多个包边界时，Agent 会展示它们的路径，并询问哪些应成为来源。把 --local 分别指向每个选中的包。

在来源内部过滤文件无法选中 monorepo 的包，因此请明确选择包。在索引过时或无关的区域之前先讨论一下——不必要的代码会耗费阅读时间和 token——但不要仅仅因为某个目录名字看起来陈旧就舍弃它。

代码如何被读取

解析是所选 Indexer 的细节，不需要你按仓库配置。Indexer 会检查语言、清单文件、入口、路由和契约，然后使用能回答读者问题的最小解析器集合。社区解析器覆盖 TypeScript/JavaScript、Go、Rush monorepo、Thrift、Protobuf、Markdown/MDX、API 契约、样式表和 SQL schema。解析器产出的事实如何变成页面，参见代码抽取。

在另一台机器上的检出

Git 只为仓库来源保存恢复配方：远程地址、固定的 commit 和模块路径，并不保存检出本身。当 Context 知识工作区在别处打开、且某个任务需要这份代码时，Agent 会提供三种选择：

1. 指向一个已有的本地检出；
2. 指定一个有边界的目录，让它在其中扫描匹配的检出；或
3. 允许 Context 把已登记的仓库克隆到 .tmp/repo/。

恢复克隆始终使用已登记的 commit，因此现有知识保持可复现。在普通模式下，Agent 会在克隆前询问；它从不扫描未指定的磁盘根目录，也不会用其他分支或相近的仓库代替。

代码继续演进时

登记会一直保持其 commit，直到你另作决定。要把知识更新到更新的 commit，请提出更新：Agent 会准备新版本，将其与现有页面引用的内容进行比较，并询问哪些页面需要修改。只有在所选修订被批准并构建之后，已处理的基线才会前移。参见更新知识。