tacit

Quick start

Requires Python 3.12+ and uv. The observer talks to any OpenAI-compatible chat-completions endpoint with tool calling; there is no LLM SDK, so switching providers is configuration only.

git clone https://github.com/kannch8765/tacit && cd tacit
uv tool install .            # puts `tacit` on your PATH

# any model behind an OpenAI-compatible endpoint
export TACIT_LLM_MODEL=deepseek-v4-flash
export TACIT_LLM_API_KEY_FILE=~/.config/tacit/key   # or TACIT_LLM_API_KEY

# optional
export TACIT_LLM_BASE_URL=https://opencode.ai/zen/v1   # the default
export TACIT_HOME=~/.tacit                              # the default

Add the two hooks to Claude Code (~/.claude/settings.json, or install the repo as a plugin with hooks/hooks.json):

{
  "hooks": {
    "Stop": [{"hooks": [
      {"type": "command", "command": "tacit hook stop", "timeout": 10}
    ]}],
    "UserPromptSubmit": [{"hooks": [
      {"type": "command", "command": "tacit hook prompt", "timeout": 10}
    ]}]
  }
}

How it works

1. Observe, without blocking

The Stop hook only records the session and its transcript path, then starts a detached worker if none is running (a file lock keeps it to one). The worker reads the transcript from a committed byte offset, takes only complete JSONL records (a half-written last line waits for the next run), and cuts them into batches of up to 200 lines.

2. Turn transcript lines into trusted evidence

Each text block, tool call and tool result becomes an evidence event with a backend-owned evidence_id, its role (user, assistant, tool) and its line number. Secrets are redacted on the whole block at this point, before anything is stored or sent. The observer model sees a catalog of these events.

3. Ground every write

The observer can only cite evidence ids; tacit copies the quote from the transcript itself, so the model never types a quote it could make up. A proposal whose ids don't resolve in the batch, or that breaks its bucket's rules, is recorded as rejected with a reason code. It is never silently saved and never silently dropped.

outcome: rejected   evidence_role_not_allowed
         world_update can't be grounded by assistant evidence
outcome: accepted   c_755179245877   (same fact, re-proposed with the tool result as evidence)

From the live smoke test: the model first grounded a world_update in its own words, was told why, and fixed it in the same turn.

4. Settle into a versioned ledger

A grounded proposal becomes one of: a new card; a reinforcement of an existing card (the same knowledge seen again attaches new evidence instead of duplicating); or a new version that supersedes the old one. Cards are never edited in place (SCD type 2): superseding closes the old version (superseded_at, superseded_by) and links the new one with supersedes. Each card keeps valid_from (when it became true) and recorded_at (when tacit learned it), so "what do we believe now?" and "what did we believe on 10-10?" are both plain queries.

5. Whisper it back

On the next UserPromptSubmit, tacit hands Claude Code the relevant cards as context, with their dates, versions and exact quotes. See Grounded whispers.

6. Ask a human when it matters

Relations the observer suggests between cards (same_as, supersedes, relates_to, contradicts) wait in tacit review. Accepting one is a ledger write too, held to the same bucket rules as the observer's: a review can't merge or replace cards across buckets.

Buckets

Every card belongs to one of five buckets. Required fields and evidence rules are enforced in code (tacit/buckets.py), not in the prompt: a proposal that breaks them is rejected with a reason code. Whether new evidence reinforces a card or replaces it is the observer's call, and a replacement is always an explicit supersedes (from the observer, or accepted in tacit review). tacit doesn't match a changed preference to the old one on its own.

Data schema

One SQLite file ($TACIT_HOME/tacit.db), stdlib sqlite3 only. Three groups of tables: the knowledge itself, the processing trail, and the conversation with the next prompt.

Knowledge

Processing trail

Back to the prompt

Batch outcome model

The hard part of a background observer isn't the model call; it's deciding when a batch is done. tacit decides by ownership: a batch is held (its cursor doesn't move) only for work the batch itself owns. Everything optional is feedback, never a verdict.

observer turn over a batch
  │
  ├─ tool error (bad args, unknown id) ─▶ fed back to the model; turn goes on
  ├─ proposal breaks a rule ────────────▶ outcome = rejected + reason code
  │                                       (settled: a recorded "no")
  ├─ whisper / link suggestion fails ───▶ optional: never holds the batch
  ▼
finalize(): hold the batch only if owned work is unsettled
  ├─ turn_failed         the model turn itself didn't complete
  ├─ attempt_retryable   a storage failure on an owned write
  └─ intent_blocking     a "remember that …" not answered yet
                         (at most 3 completed turns, then released)
  │
  ├─ nothing held ─▶ batch settled; cursor + byte offset advance
  └─ held ─────────▶ retried later from the same cursor; new lines
                     make a new, wider batch (id = hash(session,
                     start, end))

• Idempotent writes. Every write has a source key (batch + proposal), so replaying a proposal after a crash or retry doesn't duplicate it.
• Trusted intents. When the user says "remember that …", the observer must answer it with a card or an explicit decline_intent and a reason. A silent drop isn't an option.
• Everything is recorded. Batches, attempts with their retry reasons, and every proposal's outcome, so failure rates are measured, not guessed.

Grounded whispers

Two lanes hand knowledge back to the next prompt. Neither makes the prompt wait on a model.

The model only selects. tacit renders the text itself: bucket, date, version, fields, the exact quotes, what the card replaced (following supersedes links), and up to two linked cards. Contradictions always come first and are marked ⚠; related cards are chosen by lexical MMR (relevant to the prompt, not redundant with each other).

tacit · decision (as of 2026-10-15, v1, c_43e68aaf97e5): Pin pydantic to < 3
  rationale: Pydantic 3 broke request validators.
  [user] “Let's pin pydantic < 3 for now, we can revisit when 3.2 ships the fix for custom validators.”

A real queued whisper from the smoke test. Before it, the model tried to whisper without searching first and got this feedback, then searched and retried:

deliver_whisper may select only a card and snippets surfaced by a purpose=whisper search in this turn.
Nothing was surfaced yet; call search with purpose=whisper first.

Privacy & redaction

• Local ledger. Everything is stored in one SQLite file on your machine.
• What the model sees. The model you configure receives the batch's evidence and the cards its searches return, after redaction.
• Redaction runs once, early. It runs on each whole block when evidence events are built, before the block is cut to size, so the ledger, the observer prompt and every whisper see the same scrubbed text. Structured tool input is redacted leaf by leaf before it is serialized, so JSON quoting can't hide a secret.
• Numbers-only observability. stats, health and report output numbers and fixed labels, never card text.

evidence [tool line 2]: connect ETIMEDOUT 10.8.0.12:443
export DEPLOY_TOKEN=[redacted:assignment]

Observability

Health and failure rates come straight from the ledger. tacit stats rolls it up per day (batches, retryable share and reasons, proposal outcomes, rejections by code, observer turn time, whispers, intents). tacit health turns that into checks:

tacit report writes a self-contained report.html (inline SVG charts, no external assets) and the metrics.json behind it.

Repository structure

tacit/
├── tacit/
│   ├── cli.py         command line + the two hook entry points
│   ├── worker.py      detached worker, one at a time (flock)
│   ├── transcript.py  JSONL records → trusted evidence events + catalog
│   ├── redact.py      secret redaction (tokens, assignments, URLs, keys)
│   ├── observer.py    one model turn per batch, purpose-built tools
│   ├── runtime.py     write path: proposals, reinforce, intents, verdict
│   ├── buckets.py     the five buckets: fields, values, evidence rules
│   ├── store.py       the ledger: versioned cards → outcomes
│   ├── whisper.py     selection, weaving (history + related), fast lane
│   ├── text.py        search tokens: Latin words + CJK bigrams
│   ├── llm.py         stdlib OpenAI-compatible client, tool calling
│   ├── stats.py       daily rollup + healthcheck (numbers only)
│   └── report.py      report.html (inline SVG) + metrics.json
├── hooks/hooks.json   Stop → tacit hook stop
│                      UserPromptSubmit → tacit hook prompt
├── .claude-plugin/    plugin manifest
├── tests/             scripted fake model: no network, no tokens
├── demo/              made-up sessions for the live smoke test + GIF
├── docs/              DESIGN.md, demo.gif, this page
└── site/              source of this page (python site/build.py)

The design and its decisions, including a point-by-point comparison with the upstream idea, are in docs/DESIGN.md.

Live smoke test

Four short, made-up sessions run through the real observer on Gemini flash-lite (its OpenAI-compatible endpoint, no code changes): a decision, a gotcha with a fake secret in a tool result, a "remember that" confirmed by a tool result, and a later question that should bring a card back.

Run it yourself with your own key; see demo/. The offline test suite uses a scripted fake model instead: no network, no tokens.

uv sync
uv run pytest

Credits & license

• Inspired by letta-ai/claude-subconscious (MIT): the hook-driven "background agent that whispers" idea. tacit is a separate rewrite with no shared code, no Letta dependency and a different focus (grounded team knowledge).
• Co-authored with Claude Opus 5.5 and GPT 6.1 Sol.
• MIT licensed. Not affiliated with Anthropic. Claude, Claude Code and Clawd are trademarks of Anthropic.