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.25.1](https://img.shields.io/badge/version-0.25.1-purple.svg)](https://github.com/jmcentire/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://img.shields.io/badge/tests-1495%20passing-brightgreen.svg)](#)
[![MCP Plugin](https://img.shields.io/badge/MCP-Plugin-orange.svg)](#install-as-agent-mcp-plugin)

**The memory layer AI coding agents don't have.**

Kindex does one thing. It knows what you know.

It's a persistent knowledge graph for AI-assisted workflows. It indexes your conversations, projects, and intellectual work so that Claude Code, Codex, Gemini CLI, Google Antigravity, OpenCode, Cursor, and other MCP-capable agents never start a session blind. 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 that grows intelligence over time — understanding relationships, surfacing constraints, and managing exactly how much context to inject based on your available token budget.

## Install

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/jmcentire/kindex && cd kindex && make install
```

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`, `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
```

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 `kin setup-agents-md --install` works for OpenCode too.
OpenCode also supports plugins, but Kindex currently uses MCP + instructions there rather than prompt-time attention injection.

### Cursor

```bash
kin setup-cursor-mcp
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 is MCP + always-applied rules. Cursor rules provide prompt-level guidance, but Kindex does not currently install a Cursor prompt-submit hook because Cursor does not expose the same hook surface as Claude Code or Codex CLI.

## Why Kindex

### Context-aware by design
Five context tiers auto-select based on available tokens. When other plugins dump everything into context, Kindex gives you 200 tokens of executive summary or 4000 tokens of deep context — whatever fits. **Your plugin doesn't eat the context window.**

| Tier | Budget | Use Case |
|------|--------|----------|
| full | ~4000 tokens | Session start, deep work |
| abridged | ~1500 tokens | Mid-session reference |
| summarized | ~750 tokens | Quick orientation |
| executive | ~200 tokens | Post-compaction re-injection |
| index | ~100 tokens | Existence check only |

### Knowledge graph, not log file
Nodes have types, weights, domains, and audiences. Edges carry provenance and decay over time. The graph understands what matters — not just what was said.

### Operational guardrails
Constraints block deploys. Directives encode preferences. Watches flag attention items. Checkpoints run pre-flight. No other memory plugin has this.

### Cache-optimized LLM retrieval
Three-tier prompt architecture with Anthropic prompt caching. Stable knowledge (codebook) is cached at 10% cost. Query-relevant context is predicted via graph expansion and cached per-topic. Only the question pays full price. Transparent — `kin ask` just works better and cheaper.

### Team and org ready
`.kin` inheritance chains let a service repo inherit from a platform context, which inherits from an org voice. Private/team/org/public scoping with PII stripping on export. Enterprise-ready from day one.

## In Practice

A 162-file fantasy novel vault — characters, locations, magic systems, plot outlines — ingested in one pass. Cross-referenced by content mentions. Searched in milliseconds.

```
$ kin status
Nodes:     192
Edges:     11,802
Orphans:   3

$ time kin search "the Baker"
# Kindex: 10 results for "the Baker"

## [document] The Baker - Hessa's Profile and Message Broker System (w=0.70)
  → Thieves Guild, Five Marks, Thieves Guild Operations

## [person] Mia and The Baker (Hessa) -- Relationship (w=0.70)
  → Sebastian and Mia, Mia -- Motivations and Goals

0.142 total

$ kin graph stats
Nodes:      192
Edges:      11,802
Density:    0.3218
Components: 5
Avg degree: 122.94
```

192 nodes. 11,802 edges. 5 context tiers. Hybrid FTS5 + graph traversal in 142ms.

## Getting Agents to Actually Use It

Installing the MCP plugin gives the agent the tools. But agents won't use them proactively unless you tell them to. Kindex ships with recommended instruction blocks that turn passive tools into active habits. For the full agent playbook, see [docs/mcp-agent-guide.md](docs/mcp-agent-guide.md).

```bash
# Claude Code
kin setup-claude-md --install

# Codex (and OpenCode — both honor AGENTS.md)
kin setup-agents-md --install --global

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

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

# Cursor — writes ~/.cursor/rules/kindex.mdc with alwaysApply: true
kin setup-cursor-rules --install
```

This adds session lifecycle rules (start/orient/during/segment/end), explicit capture triggers (discoveries, decisions, tasks, key files, notable outputs), and search-before-add discipline. The difference between "the agent has a knowledge graph" and "the agent actively maintains a knowledge graph" is this block.

For durable work, agents should use Kindex's persistent task and knowledge
surfaces rather than host-session-only task state. Use `task_add`, `task_list`,
and `task_done` for work that must survive the current conversation; search
before adding knowledge; prefer `edit` or `supersede` over duplicate nodes; and
treat tracked `.kin` files as shipped project state, not local cache.
If the host also exposes session-local task tools, use those only for temporary
planning; durable work belongs in Kindex.

The SessionStart hook (`kin setup-hooks`) reinforces these directives at the start of every session with a "Session directives" block that reminds Claude to use kindex MCP tools throughout the session.

### What gets captured

With the directives active, the agent will:
- **Search** the graph before starting work and be