kindex

# Kindex

[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![MIT License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![v0.38.0](https://img.shields.io/badge/version-0.38.0-purple.svg)](https://github.com/wandercom/kindex/releases)
[![PyPI](https://img.shields.io/pypi/v/kindex.svg)](https://pypi.org/project/kindex/)
[![MCP Market](https://img.shields.io/badge/MCP%20Market-kindex-blue.svg)](https://mcpmarket.com/server/kindex)
[![Tests](https://github.com/wandercom/kindex/actions/workflows/ci.yml/badge.svg)](https://github.com/wandercom/kindex/actions/workflows/ci.yml)
[![MCP Plugin](https://img.shields.io/badge/MCP-Plugin-orange.svg)](#install-as-agent-mcp-plugin)

**Every agent is smart inside its own silo. Kindex lets them work together.**

Kindex does one thing. It knows what you know.

Claude Code, Codex, Gemini CLI, Google Antigravity, OpenCode, Cursor, and other MCP-capable agents each remember for themselves, and none of them can read the others. Kindex is the local knowledge graph they all read and write: continuity across sessions and restarts, handoffs between vendors, shared decisions and constraints, and live coordination while several of them work at once. Available as a **free MCP plugin** or standalone CLI.

> **Memory plugins capture what happened. Kindex captures what it means and how it connects.** Most memory tools are session archives with search. Kindex is a weighted knowledge graph with typed nodes, provenance, and decay, that surfaces constraints and decisions and manages exactly how much context to inject based on your available token budget.

Kindex is the index for an individual and a codebase: your own graph, and the repository's git-tracked `.kin/`. [Kinbase](https://kinbase.tools) is the company product above it, in development: engineering direction, architecture, standards, ownership, and history, held by named authorities and composed into every coding session. Same engine, same protocol, physically separate stores.

Docs: [kindex.tools](https://kindex.tools/) is the canonical public site, served by the companion Fly static app. This repo also publishes its `docs/` directory at [wandercom.github.io/kindex](https://wandercom.github.io/kindex/). Human setup lives in [docs/human-guide.md](docs/human-guide.md); agent operating rules live in [docs/mcp-agent-guide.md](docs/mcp-agent-guide.md).

## Install

Development preview: [Claude function hooks and signet-eval coexistence](docs/claude-function-hooks.md)
adds repo-local durable tasks, secret minimization at Kindex-owned boundaries,
and separately selectable modern/legacy adapters. The default remains compatible
legacy hooks. Function hooks are qualified on Claude Code 2.1.263; this is not a
promise that all Claude logs can be redacted or a published 1.0 release.

Pick whichever installer you already use. They all install the same `kin` and `kin-mcp` binaries.

```bash
# pip
pip install 'kindex[mcp]'

# uv (single binary, no virtualenv)
uv tool install 'kindex[mcp]'

# uvx (no install — runs from cache, useful for one-off MCP invocation)
uvx --from 'kindex[mcp]' kin-mcp --help

# from source
git clone https://github.com/wandercom/kindex && cd kindex && make install
```

### Upgrading to v0.36.0

> [!WARNING]
> Before upgrading, stop every Kindex daemon, MCP server, and older CLI
> process. A v0.35.x process does not reject schema v12 and can write
> non-canonical session paths after migration.

Dream is Kindex's background knowledge-consolidation pass: it finds related
nodes, safely merges strong duplicates, and stages weaker links for review.
The first v0.36.0 process to open an older graph creates a transaction-safe
pre-migration snapshot under
`$XDG_STATE_HOME/kindex/snapshots/<db>-<hash>/migrations/` (defaulting below
`~/.local/state/kindex/snapshots/`) before atomically migrating schema v11 to
v12. The owner-private snapshot passes SQLite integrity and source-version
checks, and a partial file is deleted if creation or validation fails.
Concurrent v0.36+ processes serialize this step through a dedicated
rollback-journal SQLite lock and recheck the schema after waiting. Migration
recovery points are retained outside the rotating ten-file
automated-merge snapshot pool. Older duplicate active session tags become paused
history, one active tag per normalized project and name is enforced, and Dream
suggestions carry an explicit title-or-node-ID identity contract and title
ambiguity is refused. No node or edge rows are deleted; legacy
domain-co-membership edges remain available as stored history but no longer
participate in semantic traversal or health metrics. `kin status` exposes the
durably recorded recovery path; normal stores also record it in `kin changelog`.

#### Rolling back the schema migration

Do not open the migrated database with v0.35.x: that version has no
forward-schema guard and can write old, non-canonical session identity. Instead:

1. While v0.36 is still installed, run `kin status` and record the `Recovery`
   path. It names the latest validated migration attempt; older attempts remain
   in the same `migrations/` directory.
2. Stop every Kindex process again.
3. Move the live database's `-wal` and `-shm` sidecars aside.
4. Copy the recorded snapshot over the live database.
5. Only then install or run v0.35.x and verify the graph.

This differs from [recovering a bad automated merge](docs/human-guide.md#recover-from-a-bad-automated-merge),
which does not change package versions. Graph-health consumers must also
recalibrate: existing node/edge/orphan/component outputs now describe the
semantic graph, while explicit stored counts expose retained lifecycle and
legacy rows. Machine-readable stats identify this contract as `metrics_schema: 2`.

Then initialize the graph:

```bash
kin init
```

Extras — combine in one install (`'kindex[mcp,llm,reminders]'`) or use `'kindex[all]'`:

| Extra | Adds |
|-------|------|
| `mcp` | `kin-mcp` MCP server (for Claude Code, Codex, Gemini, Antigravity, OpenCode, Cursor, etc.) |
| `llm` | Anthropic-powered extraction (`kin learn`, `kin ask`) |
| `vectors` | sqlite-vec for semantic similarity search |
| `reminders` | Natural-language time parsing for `kin remind` |
| `all` | Everything above |

> Homebrew and apt packages aren't published yet. Use `pip`, `uv tool`, `uvx`, or source until they are.

## Install as Agent MCP Plugin

Each agent reads MCP servers from a different config file. The `kin setup-*-mcp` commands write the right shape into the right path; the manual snippet is shown alongside in case you'd rather edit the file yourself.

### Claude Code

```bash
claude mcp add --scope user --transport stdio kindex -- kin-mcp
kin init
```

Or add `.mcp.json` to any repo for project-scope access:
```json
{ "mcpServers": { "kindex": { "command": "kin-mcp" } } }
```

The MCP server exposes 50+ native tools to supported clients: `search`, `add`, `context`, `show`, `ask`, `learn`, `link`, `edit`, `supersede`, `list_nodes`, `status`, `suggest`, `candidate_*`, `verify`, `invalidate`, `stale_check`, `graph_stats`, `graph_merge`, `dream`, `changelog`, `ingest`, `tag_start`, `tag_update`, `tag_resume`, `task_claim`, `coord_*`, `lock_acquire`, `lock_release`, `remind_*`, `mode_*`, and more.

For coding agents, install both the MCP server and the instruction file. The
instruction file tells the model how to use kindex: start a session tag, read
tracked `.kin/config`, check project policy, search before adding, capture
durable decisions, and end the tag with a summary.

### Codex

```bash
kin setup-codex-mcp
kin setup-codex-hooks
kin setup-agents-md --install --global
kin ingest codex-sessions   # optional: backfill saved Codex sessions
```

`setup-codex-hooks` installs a **SessionStart** hook (alongside the prompt/tool attention hooks), so Codex begins each session with the same auto-primed context and "use kindex" / `.kin` directive as Claude Code.

Or hand-edit `~/.codex/config.toml`:
```toml
[mcp_servers.kindex]
command = "kin-mcp"
```

### Gemini CLI

```bash
kin setup-gemini-mcp
kin setup-gemini-md --install
```

Or hand-edit `~/.gemini/settings.json`:
```json
{ "mcpServers": { "kindex": { "command": "kin-mcp", "args": [] } } }
```

### Google Antigravity

```bash
kin setup-antigravity-mcp
kin setup-antigravity-hooks
kin setup-antigravity-md --install
```

`setup-antigravity-mcp` writes the standalone MCP config shape used by
Antigravity's editor/shared config and CLI config. `setup-antigravity-hooks`
installs PreInvocation priming/prompt checks, PreToolUse advisory attention and
permission gating for Kindex config writes, and Stop-time reinforcement enqueue.

Or hand-edit `~/.gemini/config/mcp_config.json` and
`~/.gemini/antigravity-cli/mcp_config.json`:
```json
{ "mcpServers": { "kindex": { "command": "kin-mcp", "args": [] } } }
```

### OpenCode

```bash
kin setup-opencode-mcp
kin setup-opencode-hooks
kin setup-agents-md --install --global
```

Or hand-edit `~/.config/opencode/opencode.json`:
```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "kindex": { "type": "local", "command": ["kin-mcp"], "enabled": true }
  }
}
```

OpenCode reads `AGENTS.md` natively, so install the MCP server and the shared `AGENTS.md` instructions together.
The OpenCode plugin supplies periodic supervisor advice on the primary user message. See [supervision and independent health](docs/supervisor-health.md) for configuration and notification setup.

### Cursor

```bash
kin setup-cursor-mcp
kin setup-cursor-hooks
kin setup-cursor-rules --install   # writes ~/.cursor/rules/kindex.mdc
```

Or hand-edit `~/.cursor/mcp.json`:
```json
{ "mcpServers": { "kindex": { "type": "stdio", "command": "kin-mcp" } } }
```

Cursor integration includes MCP, always-applied rules, and native supervisor hooks. The adapter has automated boundary coverage; authenticated Cursor model delivery and IDE activity discovery remain unver