# Kindex Full LLM Guide

Kindex is the durable memory layer for AI-assisted work. It stores knowledge in
a local SQLite graph, exposes it through a CLI and MCP server, and gives agents
explicit operating rules for using that graph without waiting for the user to
ask.

Public surfaces:

- Canonical website: https://kindex.tools/
- GitHub Pages docs build: https://jmcentire.github.io/kindex/
- Human setup guide: https://kindex.tools/human-guide.md
- MCP agent guide: https://kindex.tools/mcp-agent-guide.md
- MCP server card: https://kindex.tools/.well-known/mcp/server-card.json
- Source: https://github.com/jmcentire/kindex
- PyPI: https://pypi.org/project/kindex/

## Install

```bash
pip install 'kindex[mcp]'
uv tool install 'kindex[mcp]'
uvx --from 'kindex[mcp]' kin-mcp --help
git clone https://github.com/jmcentire/kindex && cd kindex && make install
kin init
```

Extras:

- `mcp`: installs the `kin-mcp` server.
- `llm`: enables Anthropic-powered extraction and question answering.
- `vectors`: enables sqlite-vec semantic similarity.
- `reminders`: enables natural-language scheduling.
- `all`: installs all optional features.

## Agent Operating Contract

Agents connected to Kindex should:

1. Start or resume a session tag.
2. Search or ask Kindex before significant work.
3. Use durable Kindex tasks for work that must survive the current chat.
4. Capture decisions, constraints, questions, watches, key files, and notable outputs while they are fresh.
5. Link related concepts.
6. End the session tag with a summary.

Agents should not treat host-local task scratch as durable memory. If a repo
tracks `.kin/`, agents should treat `.kin/config`, `.kin/index.json`, and
`.kin/code-map.json` as shipped project state and regenerate generated JSON
instead of hand-editing it.

## Reviewed Memory and Trusted State

Automatic lifecycle capture is untrusted input. `compact-hook` stages bounded
candidate records and creates no durable nodes or edges. Inspect the exact
payload and freshness token, then explicitly accept, reject, prune, or erase it:

```bash
kin candidate list --status pending
kin candidate show <candidate-id>
kin candidate accept <candidate-id> --review-token <token> \
  --by reviewer --method source-check
kin candidate reject <candidate-id> --by reviewer --code not_relevant
kin candidate prune
kin candidate erase <candidate-id>
```

Verification is typed provenance, not a title convention. Use `kin verify` to
assert an actor, method, and optional RFC 3339 valid interval; use
`kin invalidate` to record an exclusive end time and reason. `--trusted-only`
search and context admit only active, explicitly verified state. Session resume
uses that trusted admission by default and is bounded by deterministic
character accounting, with an optional tokenizer callback for provider-token
guarantees.

## Grounded Retrieval

Vector search returns nearest neighbours for any query, so without a floor a
question the graph knows nothing about still pulls real nodes into context.
Kindex calibrates a similarity floor against the local corpus and reports a
verdict with every result set: `grounded`, `weak`, `ungrounded`, or
`uncalibrated`.

```bash
kin embed calibrate          # measure the null-query distribution, record the floor
kin embed calibrate --show   # read the current record
```

The floor is an immutable versioned record keyed by `provider:model` carrying
the corpus it was measured against, so a floor taken at low embedding coverage
is detected as stale rather than trusted. Config holds policy only
(`grounding.floor_percentile`, `grounding.enforce`), never the number.
Enforcement is opt-in: shadow mode reports the verdict while every row still
flows, because a miscalibrated floor produces silent false negatives, which are
worse than the visible false positives it replaces.

Agents should read an `ungrounded` verdict as "the graph does not know this"
and say so, rather than synthesising an answer from loosely adjacent rows.

## Extraction Engines

Extraction is an input, never an authority: engine output is staged into the
`capture_candidates` quarantine and never writes nodes or edges directly.
`kin extract engines` lists what is available; `kin extract eval` scores engines
against the local corpus behind a two-part gate (grounding precision as a
hallucination floor, title recall as the discriminator). An optional LLM-free
deterministic engine ships behind the `kindex[talon]` extra, excluded from
`kindex[all]` and degrading to keyword extraction when absent.

## Client Setup

```bash
# Claude Code
claude mcp add --scope user --transport stdio kindex -- kin-mcp
kin setup-claude-md --install
kin setup-hooks

# Codex
kin setup-codex-mcp
kin setup-codex-hooks
kin setup-agents-md --install --global

# Gemini CLI
kin setup-gemini-mcp
kin setup-gemini-md --install

# Google Antigravity
kin setup-antigravity-mcp
kin setup-antigravity-hooks
kin setup-antigravity-md --install

# OpenCode
kin setup-opencode-mcp
kin setup-agents-md --install --global

# Cursor
kin setup-cursor-mcp
kin setup-cursor-rules --install
```

## Reminder Wakeups

Reminders can carry shell actions, natural-language instructions, or headless
agent wakeups:

```bash
kin setup-cron

kin remind create "Continue rollout check" --at "in 10 minutes" \
  --wake codex --session last --cwd "$PWD" \
  --instructions "Check the rollout and fix any new failures."

kin remind create "Continue OpenCode build" --at "in 10 minutes" \
  --wake opencode --session last --cwd "$PWD" --wake-agent build \
  --instructions "Continue the build triage."
```

Important boundary:

- `remind_create` stores the reminder.
- Due reminders fire only when `kin remind check`, `kin remind exec`,
  `kin cron`, or an installed `kin setup-cron` schedule runs.
- Codex wakeups run `codex exec` or `codex exec resume ...`.
- OpenCode wakeups run `opencode run`, optionally with `--session`,
  `--continue`, `--dir`, `--model`, and `--agent`.
- Kindex does not reenter or interrupt an idle terminal UI unless that host
  provides a same-thread wake API.

## Core Tool Families

- Search and context: `search`, `context`, `ask`, `show`, `list_nodes`, with
  trusted-only projections on search and context.
- Knowledge capture: `add`, `edit`, `supersede`, `learn`, `link`.
- Capture review and trust: `candidate_list`, `candidate_show`,
  `candidate_accept`, `candidate_reject`, `candidate_prune`, `candidate_erase`,
  `verify`, `invalidate`.
- Session state: `tag_start`, `tag_update`, `tag_resume`.
- Durable work: `task_add`, `task_list`, `task_done`, `task_claim`,
  `task_release`.
- Coordination: `coord_start`, `coord_join`, `coord_post`, `coord_read`,
  `coord_attach`, `coord_inject`, `coord_end`.
- Locks and watches: `lock_acquire`, `lock_release`, `watch_add`,
  `watch_list`, `watch_resolve`.
- Reminders: `remind_create`, `remind_list`, `remind_snooze`,
  `remind_done`, `remind_check`, `remind_exec`.
- Graph maintenance: `status`, `suggest`, `graph_stats`, `graph_heal`,
  `graph_merge`, `dream`, `changelog`, `ingest`.
- Modes: `mode_activate`, `mode_list`, `mode_show`, `mode_create`,
  `mode_export`, `mode_import`, `mode_seed`.

## Release Verification

For release work, verify:

```bash
python3 -m pytest
mcp-publisher validate server.json
git describe --tags --exact-match HEAD
gh release view vX.Y.Z --repo jmcentire/kindex
curl -fsSL https://pypi.org/pypi/kindex/json
curl -fsSL https://kindex.tools/ | grep 'vX.Y.Z'
curl -fsSL https://kindex.tools/.well-known/mcp/server-card.json | grep 'X.Y.Z'
```

Refresh registry auth before publishing if the local MCP publisher token has
expired, then run:

```bash
mcp-publisher publish server.json
```
