> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gethandshake.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Project knowledge

> Understand the factual project bundle, project brief, repository map, and freshness controls.

Project knowledge gives an agent current project context in addition to one
session history.

## Knowledge types

Handshake maintains two types of knowledge.

### Factual records

Handshake writes deterministic records during Git-aware checkpoints:

* Checkpoint log.
* Git timeline.
* Bounded text diffs.
* Per-session timelines.

These records do not require a model.

### AI-authored documents

An agent can publish:

* `project-brief.md`: Project purpose, state, decisions, risks, and next actions.
* `repo-map.md`: Directories, entry points, data flow, and build or test commands.

Handshake adds provenance frontmatter to each document.

## Facts revision

Handshake assigns a facts revision to each project. The revision changes when
a checkpoint records material project information.

An AI-authored document declares the facts revision that its author used.
Handshake rejects a publication when that revision is not current. A later
checkpoint marks older AI-authored documents as stale.

## Authoring sequence

1. The active agent gets the first opportunity to publish current documents.
2. A configured background writer waits for the grace period.
3. The background writer starts only if the documents are still stale.
4. Handshake accepts the output only for the current facts revision.

See [Configure the background writer](/guides/background-writer).

## Knowledge bundle

Handshake stores the bundle at:

```text theme={null}
~/.handshake/knowledge/<project-id>/
├── index.md
├── project-brief.md
├── repo-map.md
├── log.md
├── git-timeline.md
├── diffs/
└── sessions/
```

Session transcripts are not exported to the bundle. Handshake omits sensitive
and generated paths from diffs. The applicable diff index records each
omission.

## Use project knowledge in a restore

Handshake adds current project knowledge to a restored session. It does not
inject an AI-authored document that is stale.

Agents use two MCP tools:

* `get_project_knowledge_context` gets the project ID, facts revision, and
  freshness state.
* `publish_project_knowledge` publishes a project brief or repository map for
  a specified facts revision.