witness — a distillation engine that keeps the history of how things changed.

witness turns a stream of text into a dated record of how its subject changed. Feed it your AI coding sessions and it tracks how you think and work. Feed it market commentary, research notes, or any document stream and it tracks how that changed instead. One pure-Go binary, a local SQLite archive plus plain markdown, served to your agent over MCP.

The thing it is built around is change over time, with provenance. When an attribute's value changes, witness does not overwrite it — it closes the old value with a date and opens a new one, and records which source records drove the shift. So the archive answers "how did this get here", not just "what is true now".

"Aah, you were at my side, all along. My true mentor... My guiding moonlight..." — Ludwig, the Holy Blade

Two ways people use it

1. Watch your own growth as you work with AI. Install it into Claude Code or OpenCode and it captures your sessions in the background — no prompting, no ritual. It distills how your thinking, workstyle, habits, and blind spots shift over months, with evidence for every claim. This is the setup witness ships configured out of the box.

It is reflection-oriented, not clone-oriented: the point is to let your agent understand you, and to leave you a re-readable record of how you thought and grew. It is a pure tool, not a coach — it captures, structures, and serves. Building a coach on top ("you've done this three times…") is left to other projects that read its output.

2. Build a change-history over any text corpus. Write a lens — a prompt describing what to notice and which dimensions to track — point witness ingest at NDJSON records, and the same four-stage engine runs. Nothing about the machinery is person-specific: raw records → observations → dated facets → narrative.

A worked example, run end to end while writing this section. A regime lens over market commentary, in an archive with no person lens enabled at all: 7 news records became 22 observations and 13 facets. Then the regime flipped hawkish→dovish, and the archive recorded it as history rather than replacing it:

inflation/core_trend
  "Disinflation has broken rather than paused: core CPI reaccelerating…"   valid_to 2026-06-…
  "Core is disinflating persistently rather than reaccelerating…"          (current)

Five facets closed and reopened that way in one review. The generated brief even flagged that its own earlier sequencing thesis had been falsified by the new data — which is the whole point of keeping the history instead of the latest snapshot.

Honest caveat: the engine is general, but everything witness ships is person-shaped — the built-in default lens, the example lens, and the summary prompts all say "notice things about the person". For a non-person corpus you write your own lens (three files) and, if you want, override the summary prompt with one file. There is no market-lens or research-lens preset yet; the machinery is domain-agnostic, the batteries included are not.

Is this you?

witness is the answer if you've ever wanted to:

• Remember what you learned across your AI coding sessions — Claude Code, OpenCode — instead of losing it when the context window resets.
• Have a second brain / AI memory for your thinking, workstyle, and habits, queryable by your agent.
• Track how you grow as a developer over time — the traps you fall into and climb out of — with provenance for every recorded change.
• Keep a journal / retrospective of how you thought and changed, re-readable months later.
• Distill a corpus you care about — market news, a knowledge base, research notes, meeting logs — into a dated history of how its state changed, not a pile of summaries. Feed it NDJSON with witness ingest.
• Query any of the above from your agent, over MCP, instead of re-explaining context every session.

Contents: How it works · Lenses · Example · Reading the archive · Commands · Install · Configuration · Your data

How it works

Four layers — one ground-truth, three derived and regenerable from it:

| Layer | Kind | What it is | |-------|------|------------| | raw (L0) | ground truth | Every turn captured verbatim — from stable Claude Code hook fields (UserPromptSubmit.prompt, Stop.last_assistant_message) or OpenCode's local SQLite session DB (message/part text). Append-only, never LLM-touched. | | observations (L1) | derived | A cheap per-session worker mines atomic, evidence-anchored observations about you, tagged by lens. Append-only. | | facets (L2) | derived, bi-temporal | A periodic reviewer synthesizes observations into evolving facets, each keeping its change history (valid_from/valid_to) — so the archive answers "how did I change," not just "who am I now." Old values are never deleted. | | profile (L4) | derived narrative | A short, human-readable markdown summary distilled from the facets — one per lens plus a cross-lens unified portrait. Generated on read: witness profile (or MCP get_profile) rebuilds it only if the facets changed, so an unread profile costs nothing. A cached read is instant; a rebuild takes ~13s. |

The archive is collect-only / pull-only: witness captures and distills everywhere, but never injects anything into a session. Nothing is pushed — you (or an agent) read the profile on demand. raw/observations/facets live in a single embedded SQLite database (witness.db); the profile is plain markdown under profile/.

Lenses

Every observation/facet carries a lens tag:

• default — global, runs on every session, cross-domain. This is the part no single-domain tracker can be: it sees that "diagnoses gaps precisely" fires in math and coding and career.
• registered lenses (e.g. math) — domain-specific lenses you register once and enable globally. witness lens register math ./math/ adds the definition (a directory) to a central registry; witness lens enable math makes it run on every session (alongside default). Lenses are shared, not tied to any repo, so the same math lens covers all your math work.

Writing a lens

A lens is a directory of three files:

math/
  lens.json     settings: name, dimensions, optional per-lens models
  extract.md    per-session — mines observations (the whole file is the prompt)
  review.md     periodic — synthesizes observations into facets (the whole file is the prompt)

// math/lens.json
{ "name": "math", "dimensions": ["speed", "independence", "proof_rigor", "abstraction", "confusion_tolerance"] }

<!-- math/extract.md -->
You are observing one session through a MATH-LEARNING lens. Notice things about the
person as a mathematician — how they reason, get stuck, and climb out…
Return ONLY a JSON array. Each element:
[{ "dimension": "proof_rigor", "observation": "…", "evidence": "…", "poignancy": 6 }]

The one rule to remember: each prompt file is used verbatim as the system prompt and replaces the built-in default prompts — it doesn't extend them — so each must be self-contained, including its output JSON schema (the tool appends the transcript / observations as the user message, but injects no schema for you).

Two complete, copy-paste-ready lenses ship as starting points. Copy the directory and rewrite the dimensions and prose for your domain:

• prompts/lens/example/ — a person lens (math learning), for tracking someone as they work.
• prompts/lens/corpus-example/ — a non-person lens (market regime), for tracking a subject that is not you. Start here for research notes, a knowledge base, incident reports, or any document stream; its README explains what has to change when the subject stops being a person.

cp -R "$CLAUDE_PLUGIN_ROOT/prompts/lens/example" ./math   # edit the files, then:
witness lens register math ./math      # copies the definition into your store (a snapshot)
witness lens enable  math               # start running it on every session

register stores a copy — editing the original afterward has no effect until you re-register. enable is the separate switch that makes it actually run.

Per-lens models (optional). By default every lens rides the default models (witness config set triage_model / distill_model). A rare heavy lens can pin a stronger model just for itself — without paying for it on every session — by adding extract_model / review_model to its lens.json:

{ "name": "math", "dimensions": ["proof_rigor"], "extract_model": "claude-sonnet-5" }

Omit a field (or leave it empty) to ride the default. Since register stores a snapshot, edit the registered copy under <witness-data-dir>/lenses/<name>/lens.json — or edit the source and re-register. Verify what a lens resolved to with witness lens show <name>.

The source directory may live anywhere. As a recommended canonical location, witness keeps the registered copy beside config.toml under <witness-data-dir>/lenses/<name>/ (normally ~/.local/share/witness/lenses/<name>/, or $WITNESS_HOME/lenses/<name>/). You can edit that registered copy directly, but this location is a convention rather than a restriction on the directory passed to lens register.

Example: one moment, end to end

Say a session contains this exchange (fictional):

you: the migration keeps failing on prod but passes locally — I'll just run it by hand and move on

you: …wait, what's actually different about prod? let me diff the two schemas before I touch anything

Here's what each layer makes of it.

raw (L0) — captured verbatim, nothing interpreted:

user  the migration keeps failing on prod but passes locally — I'll just run it by hand and move on
user  wait, what's actually different about prod? let me diff the two schemas before I touch anything

observations (L1) — the worker mines one atomic, evidence-anchored noticing:

[thinking] Caught the urge to hand-patch around a failure and redirected to isolating the
           prod/local difference before acting.
  evidence: "run it by hand and move on" → "what's different about prod? diff before I touch anything"
  poignancy: 6    lens: default

facets (L2) — after several such moments the reviewer synthesizes an evolving attribute, and keeps the history (the whole point — it shows change, not just current state):

default · thinking · diagnoses_before_acting                        confidence 0.82
  2026-05 → now       Catches the reflex to work around a failure and isolates the
                      mechanism first; gates action on understanding the cause.
  2026-02 → 2026-05   Tended to apply the first workaround that unblocked the task.   (superseded)

profile (L4) — the narrative you actually read (witness profile):

default

You've been converging on a diagnose-first way of working. A few months ago the pattern was to reach for whatever unblocked the task; now you routinely catch that urge and turn to isolating the mechanism before you touch anything…

Nothing here is pushed into your sessions