# Knowledge files (https://docs.ctxpipe.ai/docs/workspaces/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.

```text
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:

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

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

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

# Checkout
```

| Field                    | Meaning                                                                                            |
| ------------------------ | -------------------------------------------------------------------------------------------------- |
| `to`                     | Required. File-relative path of the related unit. Items without `to` are skipped.                  |
| `predicate`              | The relationship, for example `DEPENDS_ON`, `PART_OF`, `OWNS`, `SUPERSEDES`.                       |
| `confidence`             | How sure the author is: about `0.5` typical, `0.7` strong, `0.85` and above rare.                  |
| `valid_from`, `valid_to` | When the fact holds. A missing `valid_from` defaults to the time of the commit that introduced it. |
| `source`                 | Optional pointer to where the fact came from.                                                      |

`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**.

| Reason                                                        | Cause                                                                                                               | Fix                       |
| ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | ------------------------- |
| Front matter is not valid                                     | The front matter has no closing `---` line, or its YAML is not valid.                                               | Correct the front matter. |
| Repeats a linked repository or the Workspace's own repository | Shows only in results from an earlier version, for a `repositories/*.md` file. ctxpipe no longer reads these files. | None.                     |

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](/docs/workspaces/settings#hydrate-and-skipped-files).

## 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](/docs/workspaces/linked-repositories) and
[Workspace settings](/docs/workspaces/settings#sources). 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](/docs/workspaces/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.