Knowledge files

The knowledge of a Workspace is plain Markdown in its Workspace repository. ctxpipe keeps no hidden copy that can drift. Chat, search, and agents use what is on the default branch.

One file, one unit

Each Markdown file is one knowledge unit. Its path is its identity, so renaming a file creates a new unit. Keep units short and focused, and link to other units rather than copying them.

On an empty repository, use knowledge/<area>/<unit>.md. On an existing repository, follow the folders already there.

workspace-repository/
├── AGENTS.md                        # Workspace name + folder map
├── .agents/skills/ctxpipe-knowledge/
│   └── SKILL.md                     # How agents should write knowledge here
├── knowledge/
│   ├── services/checkout.md
│   └── decisions/payments-provider.md
├── .ctxpipe/workspace.yaml          # Repository format (host-only)
├── sources/                         # One file for each source
│   ├── github/acme/checkout.md
│   └── linear/engineering.md
├── linear/  notion/  confluence/    # Connector mirrors
└── slack/   pagerduty/  plain/  github/

Relationships

The knowledge graph has two layers.

Links. A relative Markdown link from one file to another becomes a LINKS_TO relationship:

Checkout calls the [payments service](../services/payments.md).

Claims. Optional claims: front matter states typed facts about the unit:

---
kind: Service
claims:
  - to: ../services/payments.md
    predicate: DEPENDS_ON
    confidence: 0.7
    valid_from: 2026-03-01
---

# Checkout

kind is optional and sets the unit's node type in the graph (Service, API, Library, Decision, Pattern, and so on). Without it, the unit appears as a generic knowledge unit.

Older facts count for less over time. Recent, well-sourced facts rank highest in answers.

Skipped files

ctxpipe skips a file that has one of the errors below, and continues with the other files. One bad file does not stop the Workspace. A skipped file stays in Files, because it is in git, but chat, MCP, search, and the graph do not use it. Settings lists the skipped files of the latest commit under Hydrate skipped N files.

Push the fix to the default branch. When ctxpipe reads the new commit, the file is a knowledge unit again, and it leaves the list.

Other errors stop the read of the whole commit. For example, a set of files that is too large shows Loading failed in Settings. See Workspace settings.

Sources and linked repositories

Each file under sources/ is a source. The GitHub source files link the code repositories of a Workspace. See Linked repositories and Workspace settings. ctxpipe does not read files in repositories/. When an organization moves to Workspaces, the upgrade pull request turns those files into source files.

What ctxpipe writes

ctxpipe changes the Workspace repository only with small commits to the default branch. Each commit does one job and has a clear message:

• the setup commit (AGENTS.md and the knowledge skill);
• knowledge extracted from linked repositories;
• connector mirrors from Linear, Notion, Confluence, Slack, PagerDuty, Buildkite, Plain, and GitHub pull requests;
• the mirror files of the sources that you add in Settings;
• upkeep such as rewriting links after a rename or filling in a missing valid_from.

ctxpipe never force-pushes. If someone else pushed first, ctxpipe rebases its change onto theirs. If both changed the same lines, ctxpipe merges the two changes before it pushes.

Changes made in Workspace chat are different: they go to a separate branch and reach the default branch only through a pull request you open.

Files under sources/ and .ctxpipe/ change only through pull requests, so a person reviews the scope before ctxpipe mirrors content.