Knowledge sources and citations

Open Workflow settings → Factory settings → Knowledge. This is where you add source material and search what CodeBook can retrieve. Approved learned notes remain in Memory. A repository memory note can cite only ready sources indexed for that same repository; citing a source does not widen who can retrieve it, and the note is withheld when the source changes, is removed or becomes unreadable.

Add a source

Choose a title, knowledge type and scope: organization, workspace, factory, workflow or an installed worker. Types include code, company, product, architecture, customer, policy, design and operations.

Upload a UTF-8 text, Markdown, CSV, JSON or source-code file up to 1 MB. CodeBook encrypts the original and stores it through SSO. It keeps bounded text chunks and their file/line provenance in its application database.

For a connected GitHub, GitLab or Gitea repository, choose the repository, file path and optional branch/ref. This indexes that selected file; it does not automatically crawl the repository. Files sync periodically. Unchanged content refreshes its timestamp without being embedded again. Deleted files stop returning chunks. Errors remain visible with Sync / retry.

Repository files, issues and pull/merge requests use the selected GitHub, GitLab or Gitea connection. GitHub discussion remains exclusive to GitHub. Uploads, approved web pages and the Jira, Linear, Slack and Notion connectors need no repository connection.

Leave the embedding model empty for text matching. To enable semantic ranking, enter an embedding model ID configured for your organization at SSO. CodeBook calls the shared model service; it does not ask for a provider key. If query embeddings are unavailable, search reports a warning and uses text matching.

Connect issues and discussions

Choose Repository issue or Pull / merge request (with reviews), select a connected repository and enter its issue or request number. Choose GitHub discussion for a GitHub discussion. CodeBook uses that repository connection; no additional token is stored in Knowledge. The connection must already be able to read the selected source.

Issue sources include the description, state, labels and conversation comments. On GitHub and Gitea, a PR number entered as an issue imports its issue-style conversation only; GitLab issue and merge-request numbers are separate, so choose the merge-request source kind for an MR. To index a pull request with its submitted reviews and inline review comments, add it as a Pull / merge request (with reviews) source instead (see pull requests, the web and ticket systems). Discussion sources include the opening post, comment/reply threads and the accepted answer’s ID. Each entry retains its original source link and update time. Minimized discussion content is excluded. Attachments and links inside posts are not fetched.

Sources refresh periodically and support Sync / retry. Unchanged text is not embedded again. Missing sources lose their indexed text; connection errors make the source unavailable for retrieval until a successful sync. CodeBook repository access is checked again before retrieval, so revoking it excludes existing indexed chunks immediately. Host-side changes to the token’s access are detected when CodeBook next contacts the host.

A source supports up to 500 comments/replies and 1 MB of text, with at most 16 API requests per GitHub conversation sync or 20 for Gitea/GitLab, 30 seconds per request and 3 MB per response. Exceeding a limit produces a visible error instead of presenting a partial conversation as complete. Source permissions, factory profiles, external-worker opt-in and freshness requirements apply as usual. For larger threads, upload a deliberately selected document.

This connects selected repository conversations. Gitea issue comments are read as one bounded list because that endpoint does not paginate; an oversized response is refused. Jira, Linear, Slack and Notion items, pages on approved web origins and pull requests with reviews are covered on their own page; Confluence has no connector. The adapters follow GitHub’s issue-comment API and Discussions API.

Control access

A source inherits its organization/workspace/factory/workflow boundary. Worker access can restrict it to selected installed workers. External runtimes are excluded by default and need an explicit source opt-in. An external runtime without an installed worker identity cannot read a worker-restricted source. Crew context requires access for every participating crew member, leader and reviewer.

A Factory knowledge profile optionally limits that factory to selected sources. Source permissions are checked before chunks are loaded. Native and crew runs check retrieved source access again before subsequent model calls; changed or revoked material stops the run so it can restart with current context.

Search and require context

Search What does CodeBook know? to preview cited results. Select a worker or external-runtime preview to check its access. Results show the source, file path and line range.

A station can require knowledge types and an optional maximum age in hours. Missing, unauthorized or stale required material blocks execution with an actionable message. The requirement checks availability and freshness; it does not prove that the source answers every question in the card.

Native, crew and external-worker briefs include ranked, authorized chunks alongside task context. Retrieval defaults to a 12,000-character budget and at most 12 chunks. This is a retrieval budget, not a tokenizer-based limit for the entire model prompt.

Relationships and limits

Link sources as depends on, implements, documents, supersedes or relates to. Links retain source permissions. These are explicit document relationships; selected-file code extraction is available below; reviewed domain extraction is available below. Jira, Linear, Slack and Notion sources, approved web pages and pull-request reviews are on their own page.

Source text is untrusted reference material. It cannot expand a worker's permissions. Workers receive citation IDs and file/line information to cite when they use a fact; review the final output for citation fidelity.

How task context fits

Native and crew work uses a shared 48,000-byte budget for the initial card evidence. The card, custom fields and checklist remain whole; if they exceed the budget, the run blocks and asks for a smaller task. Optional comments and artifacts are admitted as complete records, ranked by task-word overlap and recency, alternating categories so comments cannot consume every slot. Only the most recent 100 comments are considered by the card context service.

The context manifest reports omitted record counts. Workers are told not to infer missing evidence, and the manifest is recorded in run events. This is deterministic relevance selection, not a learned quality score. Source permissions and freshness requirements still run before knowledge is supplied, with revocation checks before subsequent model calls.

Metered factory completions have a separate 240,000-byte safety cap across instructions, operator memory, retrieved knowledge, tools and conversation history. Overflow blocks the call instead of deleting standing instructions or breaking tool-call/result pairs. These byte limits are not model-specific token-window guarantees; SSO and the provider still enforce their own limits.

External-worker briefs use a 60,000-byte envelope. Optional comment/artifact records may be omitted with counts; mandatory instructions, memory, task requirements and cited knowledge remain whole or dispatch fails. GitHub Actions receives valid JSON, and Devin receives the selected full brief rather than only the card description.

Inspect the repository graph

The Knowledge panel's Repository graph indexes declarations and imports in selected files. It uses static parsers only; source code is never executed, imported or compiled. Select a worker and external-access preview before inspecting, and search by symbol, route or path.

Supported languages: JavaScript and TypeScript (including JSX/TSX), Python (.py/.pyi), Go, Java, Rust and PHP. Each file shows a language badge. Declarations are qualified — Service.run, store.Repo.Save, com.acme.web.Api.load, Server::handle, App\Http\K::go — with source and line citations. Go records packages, structs, interfaces and receiver methods; Java classes, interfaces, enums, annotations, methods and constructors, with static and wildcard imports; Rust structs, enums, traits, unions, type aliases, macros, functions, impl and trait methods, inline modules, use trees, mod declarations and extern crate; PHP namespaces, classes, interfaces, traits, enums, methods and functions, use forms and __DIR__-relative includes. C# and Ruby are not supported: no maintained parser grammar exists for them. C++ is not in scope. A Java record parses as a method named after it, and a PHP file using Route::match is an indexing error rather than a partial graph.

An import resolves only when exactly one permitted indexed file matches at the same repository and ref; otherwise the edge is ambiguous, with its permitted candidates listed, or unresolved with a reason. Non-relative imports resolve only through a mapping the repository declares in a permitted, indexed file: tsconfig/jsconfig paths and baseUrl; a Python package directory with __init__.py or the package the importing file sits in; the go.mod module path; Java package to directory; a Rust crate root plus crate::, self::, super:: and mod files; composer.json PSR-4. A hidden configuration file supplies no mapping. When two tsconfig paths targets both exist the edge is ambiguous rather than first-wins, and a Go package with more than one permitted file is ambiguous with its files listed. Not inferred: tsconfig extends, Go replace directives, router mount prefixes, non-relative dynamic prefixes and Go HTTP routers. An unresolved edge does not disclose whether an inaccessible target exists.

Dynamic imports — import(), require() inside a function or conditional, importlib.import_module and __import__, Java Class.forName, PHP includes built from a variable — become a distinct dynamic edge, always marked possible. Its target is a literal resolved like a static import, a static prefix from a template or concatenation that lists at most 20 permitted candidates under the directory it narrows to, or opaque with a reason. Edges show relation, certainty (certain or possible), resolution, the mapping they resolved through, reasons and candidates, with filters for all, static, dynamic and unresolved/ambiguous.

Framework routes are recorded as typed rows with framework, kind, method, path, handler and line, and shown in a routes table: Next.js app router (route groups and slots dropped, private and intercepting folders skipped, dynamic segments kept, route handlers' exported HTTP methods recorded) and pages router including pages/api; Express and Koa; FastAPI and Flask decorators; Django urlpatterns; Spring @*Mapping with class prefixes; Laravel Route::verb; MasterController router.route, resources, group and master.map in config/routes.js files, with the handler resolved to its controller method (see System Map). A route's handler is linked to its declaration when one is in the same file. Django paths are shown as written in their URLconf, and mount prefixes are not applied. Static syntax does not prove a route is mounted at runtime.

Sync replaces the source's graph atomically with its text index. Removed files lose their graph, and stale hashes are not returned as current. Files indexed by an older parser show a notice and re-index on their next sync. Parsing failures, unsupported languages and limits appear in source indexing status; any syntax error means an indexing error with no partial graph. The parser accepts files up to 500 KB and records up to 2,000 declarations and 2,000 dependencies per source; inspection returns at most 250 nodes/edges and suggests narrowing the search when more exist. An empty __init__.py cannot be a source, because ingestion refuses an empty document; a package is also recognized when the importing file sits inside it.

Retrieved source context can include a small graph excerpt alongside textual citations, using the same source permissions, now carrying the routes of the retrieved files and at most five candidates per edge. This covers selected files, not a whole-repository call graph. A hidden source's route never appears, not even through search. The source-backed extraction below can propose services, databases, teams and incidents for review; it does not establish live runtime ownership. Explicit domain modeling is also available; existing document links remain separate.

Model domain relationships

Open Domain knowledge in the Knowledge panel. Add an entity for a repository, component, service, team, person, API, database, environment, incident or decision. Select a source you can edit and cite its evidence lines. Search the source above to check those lines before saving. Add a short description of what the evidence establishes; this is reviewed reference material.

Inspect the graph, then connect entities with depends on, uses, owns, implements, documents, affects, supersedes, deployed to or decided by. A relationship requires write access to its starting source and read access to its target; both must belong to the same organization. Use Edit to correct a record, or Remove to delete an entity and its relationships while keeping its document.

The graph follows the current worker, external-access and factory-profile filters. Hidden endpoints do not appear through relationship names or counts. Worker retrieval can include a bounded domain graph beside relevant source passages, with citations for both endpoints. Native and crew runs check source access and entity/relationship revisions again before another model call.

When source text changes, its entities become Evidence changed — review required. They remain visible for review but are excluded from worker context. Review the new source lines and save the entity again; its old relationships are removed so they can be established against the new evidence. Deleting a source removes its entities and incoming/outgoing relationships. This keeps reviewed claims from silently surviving changed or removed evidence.

Each source supports up to 200 entities and each entity up to 200 outgoing relationships. Inspection returns up to 250 entities/relationships; narrow the search when results are omitted. Worker context includes at most 12 of each and a separate 6,000-byte domain envelope. This graph does not infer runtime dependencies or replace SSO’s people, team membership or access controls.

Extract proposals for review

Under Domain knowledge, expand Extract domain knowledge from a source. Choose a ready source you can edit, optionally enter an exact SSO model identifier, and select Extract proposals. CodeBook uses your organization’s tool-capable model through SSO. Provider credentials remain in SSO.

Extraction proposes up to 12 entities and 20 relationships from at most 24,000 characters of indexed source text. It uses whole chunks from the beginning of the document and reports omitted chunks. Each proposal must include a quote found at its cited source lines. Relationships must connect proposed entities, and their evidence must fall within the starting entity’s citation. These checks establish that the quote exists, not that the model interpreted it correctly.

Review each quote, edit entity names, types and summaries, and check the entities you want to keep. Relationship checkboxes become available after both endpoints are selected. Nothing is selected automatically. Save reviewed selection writes the selected entities and relationships together; a conflict or invalid record leaves the graph unchanged. Duplicate names of the same type in the same source must be resolved using the existing entity editor.

Extraction does not execute tools against your systems or write graph records. Access is checked before and after the model request. Saving checks the current source hash and quoted evidence again; if the source changed, extract and review it again. Saved records follow the same permissions, stale-source review and worker-context limits as manual records. Provider-reported token usage is displayed when available; no prices or inferred token counts are shown.

Inspect context usage

Expand a run under Runs or a station’s run history to see Context usage. Native model calls report their serialized input size, largest request, cumulative input bytes, combined call time, and provider-reported input/output tokens. Failed calls are counted separately; missing token usage is shown as unavailable, not zero. Old runs have only the telemetry recorded when they ran. External runtime calls are not measured by this native-call view.

The task-evidence summary shows the initial evidence budget and omitted record counts. Byte size is not a token estimate, repeated context is counted on each call, and concurrent crew calls can sum to more time than the run took. These are usage measurements, not a quality score. Telemetry stores numerical metadata without adding copies of prompts or provider error bodies.