# Kindex MCP server

> Gives AI agents a shared local knowledge graph to store, search, and hand off project context and decisions across sessions.

- Repository: https://github.com/wandercom/kindex
- Page: https://hostedmcp.org/servers/wandercom/kindex
- Transport: stdio
- Stars: 51
- Latest version: 0.37.0

## Install

### Claude Code

```sh
claude mcp add kindex -- uvx kindex
```

### Cursor (`~/.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "kindex": {
      "command": "uvx",
      "args": [
        "kindex"
      ]
    }
  }
}
```

### VS Code (`.vscode/mcp.json`)

```json
{
  "servers": {
    "kindex": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "kindex"
      ]
    }
  }
}
```

### VS Code CLI

```sh
code --add-mcp '{"name":"kindex","type":"stdio","command":"uvx","args":["kindex"]}'
```

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "kindex": {
      "command": "uvx",
      "args": [
        "kindex"
      ]
    }
  }
}
```

### Codex

```sh
codex mcp add kindex -- uvx kindex
```

### Codex config.toml (`~/.codex/config.toml`)

```toml
[mcp_servers.kindex]
command = "uvx"
args = ["kindex"]
```

### Gemini CLI

```sh
gemini mcp add -s user kindex uvx -- kindex
```

### Gemini settings.json (`~/.gemini/settings.json`)

```json
{
  "mcpServers": {
    "kindex": {
      "command": "uvx",
      "args": [
        "kindex"
      ]
    }
  }
}
```

## Tools (66)

- `kinbase_sync`: Refresh signed Kinbase evidence; raw verifies bytes, reduced retains governance snapshots. The source events are never modified. Reduced covers local event keys and invokes exact-key explain, never project (which may submit questions).
- `search`: Search the knowledge graph with hybrid FTS5 + graph traversal. USE THIS: before starting work on a topic, before adding nodes (to avoid duplicates), and whenever you need context about a concept. Uses Reciprocal Rank Fusion to merge full-text and graph results. Returns ranked nodes with scores. Args: query: Search query text. top_k: Maximum results to return. tags: Comma-separated tags to filter results (only nodes with these tags). include_archived: Include archived nodes (fenced from default search). trusted_only: Admit only current, explicitly verified, non-contradicted knowledge. False preserves ordinary legacy-compatible recall.
- `add`: Add a knowledge node to the graph. ALWAYS `search` first to avoid duplicates. Choose the right node_type — it determines how the node behaves: - concept: facts, patterns, key files, domain terms (default, most common) - decision: "we chose X over Y because..." — architectural choices with rationale - question: open problems to investigate later — gets surfaced until answered - task: actionable work — prefer `task_add` instead (supports priority/due/linking) - skill: demonstrated ability with evidence - constraint: hard rule that MUST hold — set trigger/action in text (e.g. "never push to main without tests") - directive: soft behavioral guideline with scope (e.g. "use snake_case in Python modules") - watch: something needing periodic attention — flaky test, unstable API, known tech debt. Set owner and expiry in text. Gets surfaced in every session until resolved or expired. - checkpoint: pre-flight checklist item — verify before a specific event Args: text: The knowledge to capture (becomes title + content). Be specific. node_type: See types above. Default: concept. tags: Comma-separated tags for contextual surfacing (e.g. "kindex,python"). domains: Alias for tags (deprecated, use tags instead). audience: Visibility scope (private, team, org, public). Default: private. referent: Path or URL the claim describes (R0 binding). File paths are hashed now — use an absolute path (the MCP server's cwd is not the project's) or supply referent_digest. referent_digest: Explicit content digest (required for url/repo scope; sha256 hex, or 7-64 hex commit for repo scope). referent_scope: file | url | repo (default: url for URLs, file otherwise). asserted_at: RFC3339 claim time (default: now when binding). true_of: RFC3339 instant the referent was observed in the digested state (default: asserted_at).
- `edit`: Edit a node in place (policy-aware). Accepts a node ID or exact title. Edit classes by node type: - editable (concept, document, artifact, skill, person, project, question): every field below is allowed - additive (decision, constraint, directive, checkpoint, watch): history matters — only append and expires; use `supersede` to replace - managed (task, session, coordination): refused — use the dedicated task/session/coordination tools Args: node_id: Node ID or exact title. title: Replace the title. content: Replace the content. append: Append a dated addendum block to the content. add_tags: Comma-separated tags to add. remove_tags: Comma-separated tags to remove. intent: Replace the intent. expires: Set an expiry date (YYYY-MM-DD) — expired nodes stop surfacing and are archived by the daemon. force: Override a foreign advisory lock.
- `supersede`: Replace a node with a fresh one, preserving history. Accepts ID or title. Creates a new node (same type/tags/audience/intent), links it with a `supersedes` edge, marks the old node status='superseded', and migrates its retrieval pheromone. Use this instead of `edit` for additive types (decision, constraint, directive, checkpoint, watch) when the content must change rather than grow. Args: node_id: Node ID or exact title of the node to replace. new_text: Full replacement text (becomes title + content). expires: Optional expiry date for the new node (YYYY-MM-DD). reason: Why the node is being replaced (kept as provenance).
- `context`: Get a formatted context block for injection into conversation. Args: topic: Topic to search for (auto-detects from cwd if empty). level: Context tier (full, abridged, summarized, executive, index). max_tokens: Token budget (overrides level with auto-selection if set). trusted_only: Admit only current, explicitly verified, non-contradicted knowledge. False preserves ordinary recall.
- `candidate_list`: List quarantined automatic-capture receipts without payload fields. Args: status: Optional pending/conflicted/accepted/rejected/expired filter. limit: Maximum receipts to return.
- `candidate_show`: Show the exact untrusted candidate payload plus its freshness token. The returned token proves snapshot freshness only. It is not caller authentication, authorization, or proof of reviewer identity.
- `candidate_accept`: Accept a fresh candidate with asserted reviewer and verification method.
- `candidate_reject`: Reject and minimize a live capture candidate. Args: candidate_id: Exact capture-candidate ID. reviewed_by: Asserted reviewer identifier. disposition_code: Bounded machine disposition code.
- `candidate_prune`: Expire due pending/conflicted candidates; never promotes knowledge.
- `candidate_erase`: Erase a candidate or minimized review receipt by exact ID.
- `verify`: Assert node verification and an optional half-open valid interval. Reviewer identity is asserted audit text within the local trust boundary; this tool does not authenticate it.
- `invalidate`: Set a node's exclusive valid-time end without deleting it. Args: node_id: Durable node ID or exact title. invalidated_by: Asserted invalidating actor. disposition_code: Bounded machine invalidation reason. invalid_at: Optional timezone-aware RFC 3339 exclusive end time.
- `show`: Show full details of a node including edges and provenance. Args: node_id: Node ID or title to look up.
- `link`: Create an edge between two nodes. Links are the graph's primary value — use liberally. Choose the right relationship type: - relates_to: general connection (default) - depends_on: A requires B to function - implements: A is a concrete realization of B - contradicts: A and B are in tension - blocks: A prevents progress on B - answers: A resolves question B - supersedes: A replaces B - context_of: A provides background for B - spawned_from: A was derived from B - exemplifies: A is an example of B Args: node_a: Source node ID or title. node_b: Target node ID or title. relationship: Edge type (see above). Default: relates_to. weight: Edge strength 0.0-1.0. Use 0.7+ for strong connections, 0.3-0.5 for weak ones. reason: Why this connection exists (stored as provenance — always provide this).
- `list_nodes`: List nodes in the knowledge graph with optional filters. Args: node_type: Filter by type (concept, decision, skill, person, project, etc.). status: Filter by status (active, archived, deprecated). audience: Filter by audience (private, team, org, public). tags: Filter by tags (comma-separated, AND logic — node must have all). limit: Maximum number of nodes to return.
- `status`: Get knowledge graph health and statistics. Returns node/edge counts, type distribution, orphan count, and active operational nodes (constraints, watches, directives).
- `ask`: Ask a question of the knowledge graph. Classifies the question type (factual, procedural, decision, exploratory), searches for relevant knowledge, and returns a formatted answer. Args: question: Natural language question.
- `suggest`: Show pending bridge opportunity suggestions. These are potential connections between concepts that Kindex detected but hasn't confirmed yet. Args: limit: Maximum suggestions to show.
- `learn`: Extract knowledge from text and add it to the graph. USE THIS: after reading long files, articles, command outputs, or completing complex multi-step tasks. Summarize what happened and pass the text here for automatic concept extraction and linking. Analyzes the text for concepts, decisions, questions, and connections. Creates nodes and links automatically. Every extracted concept is grounded to a source node so it can never orphan. Args: text: Text to extract knowledge from (session notes, documentation, etc.).
- `graph_stats`: Get graph analytics: density, components, centrality, and communities.
- `graph_heal`: Diagnose and report graph health issues with actionable recommendations. Reports: - Orphan nodes (no connections) — candidates for linking or archival - Disconnected components — candidates for cross-component links - Low-weight nodes approaching archive threshold - Bridge edges (single points of failure in the graph) Use this to understand what needs attention, then use `link`, `add`, or other tools to fix issues.
- `stale_check`: Re-hash referent-bound nodes; demote stale ones from trusted recall. R0 staleness sweep: every active node carrying a file-scope referent is re-hashed against its recorded content digest. A mismatch (or missing file) records a demotion marker — the node drops out of trusted_only recall, shows " [stale-referent]" in search/context output, and becomes a re-verification candidate. Content is never deleted or rewritten. A fresh re-hash clears a previously recorded marker. Args: base_dir: Resolve relative referent paths against this directory (default: the server's cwd — prefer absolute referent paths). rebind: Node ID to deliberately re-verify instead of sweeping: re-hash its referent and rebind to the current state (moves true_of to now, keeps asserted_at, clears the stale marker).
- `graph_merge`: Merge two nodes that represent the same concept. Moves all edges from the source node to the target node, then archives the source. Use when you find duplicate or near-duplicate nodes. Policy-aware like `edit`: managed types (task, session, coordination) are always refused — their tooling owns them. Additive types (decision, constraint, directive, checkpoint, watch) are refused unless force=True — prefer `supersede` so history survives. A foreign advisory lock on either node blocks the merge unless force=True. Args: source_id: Node to merge FROM (will be archived). target_id: Node to merge INTO (will receive edges). keep: Which node to keep: 'target' (default) or 'source'. force: Merge additive types / override a foreign lock.
- `dream`: Run knowledge consolidation (dream cycle). Performs memory consolidation: fuzzy deduplication, suggestion auto-application, and bounded domain-link proposals for review. Like sleep consolidating memory — replay, strengthen, prune. Args: mode: 'lightweight' (fast, <5s), 'full' (non-LLM), or 'deep' (LLM clusters). dry_run: If True, report what would happen without making changes.
- `changelog`: Show recent changes to the knowledge graph. Args: since: ISO date/timestamp to look back from (e.g. '2026-02-20'). days: Look back N days from now (default 7, ignored if 'since' is set).
- `ingest`: Ingest knowledge from external sources. Args: source: Adapter name (github, linear, files, commits, projects, sessions) or 'all'. limit: Maximum items to ingest per adapter (0 = each adapter's own default; code is unlimited, network/LLM adapters cap at 50). repo: GitHub owner/repo for github adapter (e.g. 'jmcentire/kindex'). since: ISO date — only ingest items after this date.
- `tag_start`: Start a new session tag for tracking work context. Args: name: Human-readable tag name (e.g. 'auth-refactor'). description: What this session is about. focus: Current focus area. remaining: Comma-separated list of remaining items.
- `tag_update`: Update, segment, pause, or end a session tag. Args: name: Tag name (auto-detects active tag if empty). focus: New focus area (used for update and segment actions). description: Updated description. remaining: Replace remaining items (comma-separated). add_remaining: Add items to remaining (comma-separated). done: Remove items from remaining (comma-separated). summary: Summary for segment/pause/end actions. action: One of: update, segment, pause, end.
- `tag_resume`: Resume a session tag — get full context for continuing work. Args: name: Tag name to resume (shows active/paused tags if empty). tokens: Exact UTF-8 byte budget for the resume block. The argument name is retained for compatibility; provider-token guarantees require a direct library caller to supply that provider's exact counter.
- `task_add`: Add a task to the knowledge graph. Tasks are graph-connected -- link them to concepts, projects, or other nodes so they surface contextually when you're working in related areas. Use link_to to connect tasks to existing graph nodes by ID or title. Args: text: Task title/description. priority: 1=urgent 2=high 3=normal 4=low 5=someday. due: Optional due date ('tomorrow', '2026-03-15', 'in 3 days'). scope: 'global' (always visible) or 'contextual' (surfaces by proximity). link_to: Comma-separated node IDs or titles to link this task to. effort: Optional effort estimate (small, medium, large). project_path: Explicit repository path; do not infer from the MCP process cwd. session_id: Optional host conversation ID for contextual reminders.
- `task_list`: List tasks, optionally filtered. Args: status: Filter: open, in_progress, done, all. Default: open. scope: Filter: global, contextual, or empty for both. priority: Max priority level to show (1-5). Empty for all. project_path: Optional explicit project filter. limit: Maximum number of matching tasks to return.
- `task_done`: Mark a task as completed. Args: id: Task node ID.
- `task_claim`: Claim a task for an agent with an expiry. Args: id: Task node ID. agent: Agent/sub-agent name claiming the task (default: resolved agent id). ttl_minutes: Claim TTL. Expired claims can be taken over. note: Optional claim note. force: Override an existing unexpired claim.
- `task_release`: Release a task claim. Args: id: Task node ID. agent: Agent name. Required to match the claim unless force is true. force: Release even if the agent does not match.
- `task_get`: Get a complete structured durable task by its exact graph ID.
- `task_update`: Update task fields; omitted fields stay unchanged. Empty due clears it. expected_version provides compare-and-swap protection against concurrent edits. Use task_execute for explicit host scope and durable operation replay.
- `task_cancel`: Cancel a task without deleting its durable record or history.
- `task_execute`: Scoped typed task operation for host adapters, including durable retries. Mutations require arguments.operation_id; update accepts expected_version. Operations: create/get/list/update/complete/cancel/claim/release/reconcile. Explicit project/session scope comes from the caller, never the MCP cwd.
- `coord_start`: Start a short-lived coordination conversation. Args: name: Conversation name. task_id: Optional related task ID. agent: Agent creating the conversation (default: resolved agent id). ttl_minutes: Conversation TTL. Expired conversations are cleaned up.
- `coord_join`: Join a coordination conversation as a member. Members get read cursors (unread tracking) and receive standing inject messages in their session context. Idempotent. Args: name: Conversation ID or name. agent: Joining agent name (default: resolved agent id).
- `coord_post`: Post a message to a coordination conversation. Args: conversation: Conversation ID or name. agent: Posting agent name (default: resolved agent id). message: Message body. to: Optional target agent — message is delivered (unread counts, injection) only to them; broadcast when empty.
- `coord_read`: Read messages from a coordination conversation. Advances the reading agent's member cursor (unread tracking). Args: conversation: Conversation ID or name. since_id: Only return messages with a higher id. limit: Maximum messages to return. agent: Reading agent name (default: resolved agent id).
- `coord_attach`: Attach a graph node to a conversation as a shared resource. Attached resources surface in members' contexts when locked, so agents see who holds what. Args: name: Conversation ID or name. node_id: Node ID or title to attach.
- `coord_inject`: Manage standing inject messages on a coordination conversation. Inject messages are pushed into member agents' session context by the prime/prompt hooks until cleared. Args: name: Conversation ID or name. action: set, clear, or list. text: Message text (for set). to: Optional target agent (for set); broadcast when empty. message_id: Specific inject message id to clear (0 = clear all).
- `coord_list`: List coordination conversations. Args: status: active, ended, or all. task_id: Optional related task ID filter.
- `coord_end`: End a coordination conversation and clear transient messages. Args: conversation: Conversation ID or name. summary: Optional retained summary.
- `lock_acquire`: Acquire an advisory lock on a node for the current agent. Locks are advisory: they signal "I am working on this" to other agents (edit refusal, collab context). Expired locks never block anyone. Args: node_id: Node ID or title to lock. ttl_minutes: Lock TTL. Re-acquiring refreshes it. note: Why the node is locked. force: Take over a foreign unexpired lock.
- `lock_release`: Release an advisory lock held on a node. Args: node_id: Node ID or title to unlock. force: Clear a lock held by another agent.
- `watch_add`: Create a watch node for something needing periodic attention. Watches surface in every session's context. Use for: - Flaky tests, unstable APIs, known tech debt - Pending decisions, things to revisit - Anything Claude should keep an eye on Args: text: What to watch (becomes the node title). owner: Who owns this watch (person or team). expires: When this watch expires (YYYY-MM-DD). Auto-archived after expiry. link_to: Comma-separated node IDs/titles to link this watch to.
- `watch_list`: List watch nodes. Args: status: Filter by status: active (default), archived, all.
- `watch_resolve`: Resolve/archive a watch node. Args: id: Watch node ID. reason: Why this watch is being resolved.
- `remind_create`: Create a reminder with natural language time parsing. Args: text: What to be reminded about. when: When to fire: 'in 30 minutes', 'tomorrow at 3pm', 'every weekday at 9am'. priority: Priority level (low, normal, high, urgent). channels: Comma-separated notification channels (system, slack, email, claude). action: Shell command to execute when the reminder fires (optional). instructions: Natural language instructions for Claude to follow when due (optional). conversation_id: Optional chat/session id for scoped hook injection. scope: Reminder visibility for hook injection: chat or global. wake: Wake an agent when due: codex or opencode. wake_session: Optional host session id to resume; use 'last' for latest. wake_cwd: Optional working directory for the wake run. wake_model: Optional model override for the wake run. wake_agent: Optional OpenCode agent override for the wake run.
- `remind_list`: List reminders with optional filters. Args: status: Filter by status (active, snoozed, fired, all). priority: Filter by priority (low, normal, high, urgent).
- `remind_snooze`: Snooze a reminder. Args: id: Reminder ID. duration: Snooze duration (e.g. '15m', '1h'). Uses config default if empty.
- `remind_done`: Mark a reminder as completed. Args: id: Reminder ID.
- `remind_check`: Check for due reminders and fire notifications. Runs the reminder check cycle: finds due reminders, sends notifications, handles auto-snooze for stale fired reminders.
- `remind_exec`: Manually trigger a reminder's action. Args: id: Reminder ID.
- `mode_activate`: Activate a conversation mode. Returns the priming artifact to inject. Modes are state inductions, not instructions. They shift how you think, not what you think about. Based on research showing induced understanding outperforms direct instruction by 5.4x. Built-in modes: collaborate, code, create, research, chat. Custom modes can be created with mode_create. Args: name: Mode name (e.g. 'collaborate', 'code', 'create'). session_context: Optional prior session context to resume from.
- `mode_list`: List available conversation modes (built-in and custom).
- `mode_show`: Show details of a conversation mode including its primer, boundary, and permissions. Args: name: Mode name.
- `mode_create`: Create a custom conversation mode from a primer, boundary, and permissions. A primer is a state induction (~80 words) that establishes how to think. A boundary defines what quality means for this mode. Permissions state what's explicitly allowed (tangents, pushback, etc). Args: name: Mode name (short, lowercase, no spaces). primer: The mode-setting passage. Under 80 words. Not instructions. boundary: 2-3 sentences defining output quality for this mode. permissions: What's explicitly permitted to keep the conversation alive. description: Optional one-line description. link_to: Comma-separated node IDs/titles to link this mode to.
- `mode_export`: Export a mode as a portable, PII-free artifact (JSON). Args: name: Mode name to export.
- `mode_import`: Import a mode from a portable artifact (JSON string). Args: artifact_json: JSON string of the mode artifact.
- `mode_seed`: Seed the default conversation modes into the graph. Idempotent.

## FAQ

### Where does Kindex store its data?

It keeps a local SQLite graph in ~/.kindex/ plus a per-repository git-tracked .kin/ directory, so nothing leaves your machine unless you configure a provider.

### How do I install Kindex for an MCP client?

Install the package with the mcp extra via pip or uv, then register kin-mcp with your agent. Plugins and setup commands also exist for Claude Code and Codex.

### Can several different AI agents share the same memory?

Yes, Kindex is designed as one local knowledge graph that multiple MCP-capable agents read and write, giving continuity across sessions and handoffs between vendors.

### What tools does the Kindex MCP server expose?

It exposes more than 50 native tools such as search, add, context, ask, learn, link, supersede, status, dream, and task_claim.

### Can I limit an agent to one repository's memory?

Yes, run kindex-lite with a --repo path to bind the server to that repository's .kin graph without global-graph fallback.
