log

Read snapshot-centered semantic history with artifact-backed collaboration state

What It Does

log reads commit-ordered snapshot history and summarizes how indexed knowledge changed semantically across commits. Unlike git log, the default unit is not "what files changed?" but "what searchable knowledge changed for the next agent, what should still be believed, and what is still open?"

When To Use / When Not To Use

When to use it

You want to understand why retrieval changed between commits.
You want a semantic summary of added, modified, and deleted indexed documents.
You want the artifact-backed beliefs, open loops, and evidence that belong to a snapshot.
You want to inspect snapshot history without opening manifest files manually.

When not to use it

You only need the current repository state. Use status.
You want direct retrieval hits for a question. Use query.
You want to resume active work from working memory. Use memory recall.

Syntax

pnpm ragit log [revRange] [--max-count <n>] \
  [--view minimal|default|full] [--type <docType>] \
  [--path <glob>] [--show-missing] \
  [--format text|json|both]

Arguments And Options

[revRange]: Optional git revision range such as HEAD~10..HEAD.
-n, --max-count <n>: Limit the final number of emitted entries.
--view minimal|default|full: Choose one-line scan output, semantic blocks, or richer per-document detail.
--type <docType>: Filter the history to one canonical document type.
--path <glob>: Filter indexed docs by a repository-local glob.
--show-missing: Include commits that do not have a snapshot manifest.
--format text|json|both: Choose human text, JSON, or both.
--cwd <path>: Run against another repository.

Input And Output Contract

There is no JSON payload input for log.
Default output is semantic history text, not raw commit history text.
JSON output includes revRange, maxCount, showMissing, filters, entries, and redactionSummary.
Each indexed entry also carries a sibling semantic block alongside snapshot.
Semantic evidence and summaries are re-masked before projection.

{
  "entries": [
    {
      "commitSha": "abc123",
      "subject": "update auth docs",
      "snapshot": {
        "status": "indexed",
        "docs": 3,
        "chunks": 12,
        "delta": {
          "added": 1,
          "modified": 1,
          "deleted": 0
        },
        "types": {
          "adr": 1,
          "spec": 2
        },
        "changed": [
          {
            "path": "docs/auth/api.spec.md",
            "status": "M",
            "docType": "spec"
          }
        ]
      },
      "semantic": {
        "available": true,
        "headline": "beliefs=2 open_loops=1 evidence=2 artifacts=4",
        "counts": {
          "beliefs": 2,
          "openLoops": 1,
          "evidence": 2,
          "artifacts": 4
        }
      }
    }
  ]
}

Examples

The examples below use one consistent sample repository so you can compare the views directly.

`minimal` view

pnpm ragit log --view minimal --max-count 5

# ragit log
- entries: 5
- show_missing: false
- view: minimal
- rev_range: HEAD
- max_count: 5
- type_filter: none
- path_filter: none
 
b5537bb indexed docs=10 chunks=26 +0 ~0 -1 | adr=1 ddd=1 glossary=1 pbd=1 plan=2 prd=1 spec=2 srs=1 | semantic beliefs=0 open=0 evidence=0 artifacts=0 | remove old adr
61449a7 indexed docs=11 chunks=27 +9 ~1 -0 | adr=2 ddd=1 glossary=1 pbd=1 plan=2 prd=1 spec=2 srs=1 | semantic beliefs=2 open=1 evidence=2 artifacts=4 | update spec and add plan
e783de5 indexed docs=2 chunks=2 +2 ~0 -0 | adr=1 spec=1 | semantic beliefs=0 open=0 evidence=0 artifacts=0 | seed docs

`default` view

pnpm ragit log --view default --max-count 1

# ragit log
- entries: 1
- show_missing: false
- view: default
- rev_range: HEAD
- max_count: 1
- type_filter: none
- path_filter: none
 
commit 61449a78c559f4eefccfab4834c6b4b0c032f6b0
Subject: update spec and add plan
Author: ragit-test
AuthoredAt: 2026-04-09T23:30:32+09:00
 
Snapshot: indexed (2026-04-09T14:30:33.368Z)
Based on: e783de501e1271eebac967830affa1893676e6fc
Knowledge: docs=11 chunks=27
Semantic delta: +9 modified=1 deleted=0
Semantic: beliefs=2 open_loops=1 evidence=2 artifacts=4
Semantic counts: beliefs=2 open=1 evidence=2 artifacts=4
Beliefs:
  - Keep answers concise [feedback reviewed] User preference confirmed for future agent responses.
Open loops:
  - Finalize refresh-token boundary [openLoop captured] Patch auth spec before resuming implementation.
Evidence:
  - art_failure_1/evid_1 [failure captured] Error: token refresh regression
Artifacts:
  - art_feedback_1 [feedback reviewed session] Keep answers concise
Changed:
  A .ragit/guide/templates/adr.template.md [adr]
  A .ragit/guide/templates/ddd.template.md [ddd]
  A .ragit/guide/templates/glossary.template.md [glossary]
  A .ragit/guide/templates/pbd.template.md [pbd]
  A .ragit/guide/templates/plan.template.md [plan]
  A .ragit/guide/templates/prd.template.md [prd]
  A .ragit/guide/templates/spec.template.md [spec]
  A .ragit/guide/templates/srs.template.md [srs]
  M docs/auth-api.spec.md [spec]
  A docs/rollout.plan.md [plan]
Types:
  adr=2
  ddd=1
  glossary=1
  pbd=1
  plan=2
  prd=1
  spec=2
  srs=1

Include missing snapshots

pnpm ragit log --show-missing --max-count 4

# ragit log
- entries: 4
- show_missing: true
- view: default
- rev_range: HEAD
- max_count: 4
- type_filter: none
- path_filter: none
 
commit b5537bb6af70f7a90037d618a2f608f1fb1fd660
Subject: remove old adr
Author: ragit-test
AuthoredAt: 2026-04-09T23:30:33+09:00
 
Snapshot: indexed (2026-04-09T14:30:34.204Z)
Based on: 61449a78c559f4eefccfab4834c6b4b0c032f6b0
Knowledge: docs=10 chunks=26
Semantic delta: +0 modified=0 deleted=1
Changed:
  D docs/auth-boundary.adr.md [adr]
Types:
  adr=1
  ddd=1
  glossary=1
  pbd=1
  plan=2
  prd=1
  spec=2
  srs=1
 
commit 9ad31c2b9b72a8e3e0d8b736ee11f4f8dc3d8f3a
Subject: notes only
Author: ragit-test
AuthoredAt: 2026-04-09T23:30:31+09:00
 
Snapshot: missing
Knowledge: no indexed snapshot for this commit
Semantic: No semantic overlay available because this commit has no indexed snapshot.

JSON for agents

pnpm ragit log HEAD~10..HEAD --max-count 2 --format json

{
  "command": "log",
  "ok": true,
  "version": "1.0.1",
  "cwd": "/repo",
  "data": {
    "revRange": "HEAD~10..HEAD",
    "maxCount": 2,
    "showMissing": false,
    "view": "default",
    "filters": {
      "docType": null,
      "path": null
    },
    "entries": [
      {
        "commitSha": "61449a78c559f4eefccfab4834c6b4b0c032f6b0",
        "subject": "update spec and add plan",
        "authorName": "ragit-test",
        "authoredAt": "2026-04-09T23:30:32+09:00",
        "snapshot": {
          "status": "indexed",
          "createdAt": "2026-04-09T14:30:33.368Z",
          "previousSnapshotSha": "e783de501e1271eebac967830affa1893676e6fc",
          "docs": 11,
          "chunks": 27,
          "delta": {
            "added": 9,
            "modified": 1,
            "deleted": 0
          },
          "types": {
            "adr": 2,
            "ddd": 1,
            "glossary": 1,
            "pbd": 1,
            "plan": 2,
            "prd": 1,
            "spec": 2,
            "srs": 1
          },
          "changed": [
            {
              "path": "docs/auth-api.spec.md",
              "status": "M",
              "docType": "spec"
            },
            {
              "path": "docs/rollout.plan.md",
              "status": "A",
              "docType": "plan"
            }
          ]
        }
      }
    ]
  },
  "warnings": []
}

Failures And Cautions

log is snapshot-centered, so commits without manifests are hidden unless you ask for --show-missing.
--type and --path filter snapshot content, not raw git diffs.
Missing commits cannot produce semantic document deltas because no snapshot exists for them.
The semantic overlay is derived from snapshot-bound artifact entries only. It does not replay the event ledger and it does not read raw transcripts back into history.

log

On this page