---
summary: "Automatic local Git history for Knowledge vaults: what is committed, failure states, and recovery boundaries"
read_when:
  - You want to inspect or understand the Git repository inside a Knowledge vault
  - A Knowledge receipt shows git state pending or unavailable
  - You are planning backups of Knowledge data
title: "Knowledge local history"
sidebarTitle: "Local history"
---

Knowledge keeps a local Git history of each store's vault. Part of the
[Knowledge plugin](/plugins/knowledge) guide.

## Policy

Git is used whenever the `git` executable is installed and `writesEnabled` is
`true`. There is no separate opt-in. The first content checkpoint initializes
`<store>/vault/.git` if it is missing, or reuses an existing repository at exactly
that root. An enclosing repository is never adopted.

There are no remotes, fetch, pull, push, or GitHub integration, and no
credentials or network access are needed.

## Publication and checkpoints

1. A publication validates its files and journals its intent in a short SQLite
   transaction, then installs and syncs the record and retained evidence outside
   the SQLite write lock. The accepted intent remains recoverable throughout.
   Attachments likewise retain committed chunks until their files are durable.
2. The transaction that acknowledges the publication queues the exact changed
   bytes in `state.sqlite`, after rechecking the current request and vault
   checkpoint. A retry after file installation settles that request once.
3. Knowledge commits that batch outside a SQLite write transaction, then records
   the commit and receipt together in a short transaction. Queued batches stay
   ordered; a retry after interruption reuses the checkpoint commit.

The queue is an outbox, not a second knowledge store; Markdown stays
authoritative. Because exact snapshots are queued, a Git outage followed by more
edits does not lose intermediate versions.

A failed Git step never rolls back a publication or turns it into a conflict.
Receipts report `git.state` as `committed` (with `git.commit`), `pending`, or
`unavailable`. **Activity & issues** in the Knowledge page shows these states with
a retry control. `knowledge_resume` retries a publication's checkpoint, and
ordinary authorized scans retry waiting batches. If Git is installed later, queued
versions are committed in order. There is no background retry timer.

## What gets committed

- Each successful publication gets one commit with exactly its records and
  evidence.
- The first scan of a partition commits a baseline of its Markdown and YAML.
  Later scans group observed external edits, renames, and deletions into one
  checkpoint. Edits made between two scans cannot be reconstructed.
- Non-media originals below 100 MiB are committed as exact blobs. Larger
  originals and media stay outside automatic snapshots.
- Unrelated working-tree edits and staged content are not swept into a
  publication commit. Knowledge never checks out, resets, or overwrites working
  files. Updating the working index reuses the exact committed blobs, including
  when retrying an interrupted checkpoint.
- Commits name the Knowledge service as committer and label the actor (`agent`,
  `operator`, or external observation). These labels are coarse provenance, not
  authenticated identities.
- Hooks, clean/smudge filters, signing, and network commands are not used. User
  and global Git configuration are not changed.

`vault.json`, recovery files under `.knowledge-history/`, and SQLite are not
committed.

## Failures and recovery

Repository problems are not treated as missing Git. Permissions, locks, a
detached HEAD, linked worktree `.git` files, malformed repositories, or an
in-progress merge leave visible `pending` checkpoints. Fix the repository and
retry. A stale lock is never removed automatically. Finish manual merges or
rebases before automatic history can continue, and run only one Gateway against a
vault.

Local Git is content history, not a full backup. Keep the registry,
`state.sqlite`, and the vault together. Deleting or replacing `.git` is not a
restore workflow.

<Warning>
The repository covers the whole vault, including every conversation partition.
Plugin access checks do not filter it. Do not share the `.git` directory as if
it were scoped.
</Warning>