kindex-modern

Kindex

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 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 is the canonical public site, served by the companion Fly static app. This repo also publishes its docs/ directory at wandercom.github.io/kindex. Human setup lives in docs/human-guide.md; agent operating rules live in docs/mcp-agent-guide.md.

Install

Development preview: Claude function hooks and signet-eval coexistence adds repo-local durable tasks, secret minimization at Kindex-owned boundaries, and separately selectable modern/legacy adapters. The default remains compatible legacy hooks. The modern adapter is a Claude Code mod: it installs on Claude Code 2.1.287 or newer when that host's claude plugin validate accepts it (last verified on 2.1.288). 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.

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

As a plugin (MCP server, skills, and session hooks in one install):

claude plugin marketplace add wandercom/kindex
claude plugin install kindex@kindex

or, inside a session, /plugin install kindex --marketplace wandercom/kindex.

What the plugin runs:

• MCP server (scripts/claude-plugin/kin-mcp): your installed kin-mcp when one is on PATH, so the server and the kin CLI share one version and one database. Otherwise it runs the matching PyPI release with uvx --from 'kindex[mcp]==<version>' kin-mcp, which downloads kindex and its dependencies from PyPI once and caches them. That needs uv; without uv or kindex it exits with an install hint.
• Hooks (hooks/hooks.json, through scripts/claude-plugin/kin): session start, prompt submit, pre-tool-use, pre-compact and stop call your installed kin to prime context, check prompts against the graph and capture the session. Without an installed kin they do nothing. They source ~/.profile first so a kin installed by pipx, uv or Homebrew is found.
• Skills: kindex-prime, kindex-capture, kindex-learn.

Everything stays on your machine: the graph is a local SQLite database (~/.kindex/ and per-repo .kin/). Nothing is sent anywhere unless you configure an LLM or embedding provider (see Privacy).

Or as a bare MCP server:

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

Or add .mcp.json to any repo to register the server for that project:

{ "mcpServers": { "kindex": { "command": "kin-mcp" } } }

Registration scope does not restrict graph access. For an agent that should use only one repository's memory, run kindex-lite --repo /absolute/path/to/repo instead. It binds the MCP server to that repository's .kin graph and Kinbase reads, without global-graph fallback. Kinbase submission and write-capable status require the launcher's --allow-kinbase-submit; --no-kinbase omits Kinbase entirely. See repository-bound MCP for configuration and the isolation boundary.

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-opencode-hooks
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. The OpenCode plugin supplies periodic supervisor advice on the primary user message. See supervision and independent health for configuration and notification setup.

Cursor

kin setup-cursor-mcp
kin setup-cursor-hooks
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 includes MCP, always-applied rules, and native supervisor hooks. The adapter has automated boundary coverage; authenticated Cursor model delivery and IDE activity discovery remain unverified. No Cursor account is needed to use Kindex with the other supported agents. See supervision and independent health.

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.

Answers from dated evidence

kin ask answers in one model call from dated evidence: the matching nodes in chronological order with today's date and your standing directives, trimmed to the messages that bear on the question, within a small budget for a single fact and a wider one for counts, lists, orderings, summaries and advice. Conversation facts and per-person profiles written by kin digest let it answer from a few thousand tokens, and relative dates in the evidence arrive already resolved. In a terminal the answer streams as it is written. The answer rules cover updated values, counts across conversations, date arithmetic and missing details. kin ingest conversations --directory DIR stores chat transcripts without loss for it to search. The MCP ask tool returns the same dated evidence to the agent that called it (and drafts the answer itself with answer=true); context(level="evidence") returns it for a topic.

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.

# 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.

For MCP clients in a repository, retain either project- or global-qualified references when reads supply them, and pass them unchanged to follow-up tools. In dual-graph sessions, use those qualified evidence IDs in source_refs when a new node or task derives from existing knowledge. Ordinary single-store and profile responses keep legacy raw IDs; source_refs does not accept those raw IDs. Search again after restarting the MCP server because qualified reference tokens are bound to its store selection. See Profiles for read scopes and write routing.

The Claude SessionStart hook (kin setup-hooks) and Codex hooks (kin setup-codex-hooks) reinforce these directives at the start of supported sessions with a "Session directives" block that reminds the agent 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 before adding nodes
• Add discoveries, decisions, key files, notable outputs, and new terms as they emerge
• Link related concepts when connections are found
• Learn from long files and outputs via bulk extraction
• Tag sessions to track work context across conversations
• Remind with actions for deferred tasks (shell commands or headless agent wakeups)

Actionable Reminders

Reminders can carry shell commands, natural-language instructions, or a headless agent wakeup. When due, the daemon executes them automatically — simple commands run directly, complex Claude tasks launch claude -p, Codex wakeups run codex exec, and OpenCode wakeups run opencode run. Wakeups can resume a known host session id, or last for the latest session when the host supports that. This starts/resumes a headless turn from Kindex's daemon/cron context; it does not interrupt an idle TUI unless the host itself exposes a same-thread automation/server wake path. A Stop hook guard can block Claude from exiting when actionable reminders are pending, but it is opt-in because Claude displays visible "Blocked by hook" output when a Stop hook blocks.

Important boundary: remind_create records the reminder. Something must later run kin remind check, kin remind exec, kin cron, or an installed kin setup-cron schedule for due reminders to fire. Wake reminders are a Kindex capability for Codex and OpenCode because those clients expose headless commands; they are not a reentrant scheduler for an already-idle interactive session.

Hook-time reminder injection uses a scoped reminder board. When a client supplies a chat/session id (conversation_id, chat_id, session_id, CLAUDE_SESSION_ID, CODEX_SESSION_ID, OPENCODE_SESSION_ID, CURSOR_SESSION_ID, etc.), Kindex injects only reminders scoped to that id plus reminders explicitly marked --scope global. Legacy unscoped reminders still work for manual kin prompt-check, daemon checks, and notifications, but they are not injected into an identified chat by default.

# Kill a cloud instance in 1 hour (but download results first)
kin remind create "Kill vast.ai instance" --at "in 1 hour" \
  --action "vastai destroy instance 12345" \
  --instructions "Download results from /workspace/ before killing"

# Wake a headless Codex or OpenCode turn when due
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."

# Chat-scoped or intentionally global hook-visible reminders
kin remind create "Deploy checklist" --at "tomorrow 9am" \
  --conversation-id "$CLAUDE_SESSION_ID" --attention-trigger deploy
kin remind create "Monthly billing review" --at "next Monday 9am" --scope global

# Manual trigger
kin remind exec --reminder-id <id>

Dream — Knowledge Consolidation

Kindex can run fuzzy deduplication, auto-apply high-confidence pending suggestions, and stage bounded domain-link proposals for review. Resolved fuzzy matches are not recreated. The pending domain-review queue is capped per graph (reminders.dream_max_domain_link_suggestions, 50 by default), proposals are round-robin across domains, and rejected pairs stay rejected. The setting lives under reminders because scheduled and Stop-hook Dream runs use the reminder/maintenance configuration. Shared domains are never materialized directly as semantic edges. Like memory consolidation during sleep — replay important paths and prune noise without turning tags into topology.

# See exact merge and domain-link proposals (no changes)
kin dream --dry-run

# Run full consolidation
kin dream

# Fast path: dedup + suggestions only
kin dream --lightweight

# Include LLM-powered cluster summarisation
kin dream --deep

# Fork and return immediately; repeated detached starts are throttled
kin dream --detach --lightweight

Default triggers are manual CLI, periodic cron (step 11 of kin cron), and a throttled detached Stop hook. File locking prevents concurrent cycles, and reminders.dream_min_interval prevents hooks or cron from relaunching dream repeatedly after a recent start. Set reminders.dream_on_stop_enabled: false to disable Stop-time detached dream while leaving manual and cron dream available.

Conversation Modes

Modes are reusable conversation-priming artifacts that induce a processing mode in an AI session. Based on research showing that induced understanding outperforms direct instruction by 5.4x, and that 15 tokens of mode-setting capture 98.8% of achievable priming benefit.

Five built-in modes: collaborate, code, create, research, chat. Create custom modes from any session and export them for team sharing (PII-free).

# Seed default modes
kin mode seed

# Activate a mode — outputs the priming artifact
kin mode activate collaborate

# Create a custom mode
kin mode create debug-session \
  --primer "We're hunting a bug. Precision over speed..." \
  --boundary "Show your reasoning chain. Name assumptions." \
  --permissions "Speculate about root causes freely."

# Export for team sharing (PII-stripped)
kin mode export collaborate > collaborate.json

# Import a teammate's mode
kin mode import their-mode.json

Modes are not instructions — they're state inductions. A primer establishes how to think, a boundary defines what quality means, and permissions state what's allowed. The AI shifts processing mode rather than following a checklist.

Quick Start

# Add knowledge (with optional tags)
kin add "Stigmergy is coordination through environmental traces" --tags biology,coordination

# Search with hybrid FTS5 + graph traversal
kin search stigmergy
kin search coordination --tags biology   # filter results by tag

# Ask questions (with automatic classification)
kin ask "How does weight decay work?"

# Get context for AI injection
kin context --topic stigmergy --level full

# List and filter by tags
kin list --tags python,ml              # nodes tagged with both
kin list --type concept --tags ai      # combine type and tag filters

# Track operational rules
kin add "Never break the API contract" --type constraint --trigger pre-deploy --action block

# Check status before dep