Skip to main content
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.

​
Knowledge bundle

Handshake stores the bundle at:
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.