Kindex

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.

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

Install

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

# 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

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

kin init

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

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

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

Or add .mcp.json to any repo for project-scope access:

{ "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

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:

[mcp_servers.kindex]
command = "kin-mcp"

Gemini CLI

kin setup-gemini-mcp
kin setup-gemini-md --install

Or hand-edit ~/.gemini/settings.json:

{ "mcpServers": { "kindex": { "command": "kin-mcp", "args": [] } } }

Google Antigravity

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:

{ "mcpServers": { "kindex": { "command": "kin-mcp", "args": [] } } }

OpenCode

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

Or hand-edit ~/.config/opencode/opencode.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. OpenCode also supports plugins, but Kindex currently uses MCP + instructions there rather than prompt-time attention injection.

Cursor

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

Or hand-edit ~/.cursor/mcp.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.

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.