Kindex

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/ - /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]== ' 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, query_context, task_claim, coord_*, lock_acquire, lock_release, remind_*, mode_*, and more.

For explicitly scoped read-only query preparation and optional additive retained evidence, see query context. The supported pilot paths are kin context-query and full MCP query_context.

Offline recall cues are an experimental, disabled-by-default lexical sidecar. Explicitly prepare a bounded batch with kin recall-cues build --limit 100 (repeat --node ID to select sources), and inspect counts with kin recall-cues status; both accept the shared --config, --data-dir, --profile and --json flags after the subcommand. MCP exposes the same operations as recall_cues_build(node_ids=None, limit=100) and recall_cues_status().

Enable supplemental retrieval in your selected configuration:

recall_cues:

enabled: true candidate_limit: 20 # 1..100 additional source candidates rank_weight: 0.10 # relative ranking weight; not factual confidence

Builds make no provider calls and change only derived metadata. Each source gets at most three aliases or framed exact source spans; source alias origin does not assert human authorship. The index uses only the supporting source wording, while answers and context receive only original source nodes. This extractive arm cannot invent missing synonyms or demonstrate personalized memory benefits. It has an additional candidate/index budget, so compare it with ordinary retrieval explicitly. Source changes invalidate cues immediately; run an explicit bounded rebuild to refresh them. Roll back retrieval by setting enabled: false; stored sidecars remain available for later rebuilding. There is no automatic maintenance, generation service, or background scheduling.

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. Codex runs new or changed hooks only after you trust them, at its startup review prompt or in /hooks; until then it does not run them, SessionStart included.

Or hand-edit ~/.codex/config.toml:

[mcp_servers.kindex]

command = "kin-mcp"

Gemini CLI

`ba