Kindex — The memory layer Claude Code doesn't have
Description: The memory layer Claude Code doesn't have. A persistent knowledge graph so your AI assistant never starts a session blind. Free Claude Code plugin with 13 MCP tools, 42 CLI commands, and cache-optimized LLM retrieval.

# kindex

The memory layer Claude Code doesn't have.

Kindex does one thing. It knows what you know. A persistent knowledge graph so your AI assistant never starts a session blind.

$ `pip install kindex[mcp]`
$ `claude mcp add -s user -t stdio kindex -- kin-mcp`
v0.5.0 Claude Code Plugin 16 MCP Tools 43 CLI Commands MIT License Free

## Why Kindex

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.

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

### Cache-Optimized LLM Retrieval

Three-tier prompt architecture with Anthropic prompt caching. Stable knowledge cached at 10% cost. Query-relevant context predicted via graph expansion. Only the question pays full price. Transparent — `kin ask` just works better and cheaper.

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

## 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 ## [document] Hessa the Baker's Story (w=0.70) → Mia -- Backstory, Mia -- Character Arc ## [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.

## Install as Claude Code Plugin

Two commands. Zero configuration. Claude gets 13 native tools for your knowledge graph.

# Install and register (one time) $ pip install kindex[mcp] $ claude mcp add --scope user --transport stdio kindex -- kin-mcp $ kin init # That's it. Claude Code now has: search — hybrid FTS5 + graph search add — capture knowledge with auto-linking context — formatted context block at any tier show — full node details with edges ask — question classification + answer learn — extract knowledge from text link — create edges between nodes list_nodes — browse with filters status — graph health + operational summary suggest — bridge opportunity suggestions graph_stats — centrality, communities, density changelog — recent changes ingest — ingest from external sources

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

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

Also works as a standalone CLI (`kin search`, `kin add`, etc.) and via Claude Code hooks. Use whichever integration fits your workflow.

## Context Tiers

The core differentiator. Other plugins inject context and hope for the best. Kindex manages exactly how much based on what's available.

Tier | Budget | Use Case
--- | --- | ---
full | ~4000 tokens | Session start, deep work — everything relevant
abridged | ~1500 tokens | Mid-session reference — key facts and connections
summarized | ~750 tokens | Quick orientation — what matters right now
executive | ~200 tokens | Post-compaction — just the essentials
index | ~100 tokens | Existence check — "I know about X"

Auto-selected via `--tokens` budget or set explicitly with `--level`. The MCP `context` tool does this automatically.

## Quick Start (CLI)

# Initialize a knowledge store $ kin init # Add knowledge $ kin add "Stigmergy is coordination through environmental traces" Created node: stigmergy-is-coordination-th (concept) # Search with hybrid FTS5 + graph traversal $ kin search stigmergy 0.85 stigmergy-is-coordination-th concept Stigmergy is coordination... # Ask questions (with automatic classification) $ kin ask "How does weight decay work?" [procedural question] # Track operational rules $ kin add "Never break the API contract" --type constraint --trigger pre-deploy # Ingest from all sources (GitHub, git, sessions, files) $ kin ingest all

## Architecture

SQLite + FTS5 primary store and full-text search nodes: id, title, content, type, weight, audience, domains, extra edges: from_id, to_id, type, weight, provenance fts5: content synced via triggers Retrieval pipeline: FTS5 BM25 ──┐ Graph BFS ──┼── RRF merge ── tier formatter ── context block (vectors) ──┘ | full | abridged | summarized | executive | index LLM cache tiers (kin ask): Tier 1: codebook (stable node index) cached @ 10% cost Tier 2: query-relevant context cached per-topic @ 10% cost Tier 3: user question full price, tiny Three integration paths: MCP plugin ──> Claude calls tools natively (search, add, learn, ...) CLI hooks ──> SessionStart/PreCompact/Stop lifecycle events Adapters ──> Entry-point discovery for custom ingestion sources

### Node Types

Knowledge: concept, document, session, person, project, decision, question, artifact, skill

Operational: constraint (invariants), directive (soft rules), checkpoint (pre-flight checks), watch (attention flags)

## .kin Voice & Inheritance

Companies publish `.kin` files that encode their voice, standards, and context. Teams inherit from orgs. Repos inherit from teams. The knowledge graph carries the voice forward automatically.

### Org Voice

# ~/.kindex/voices/acme.kin name: acme-voice audience: org voice: tone: precise, direct principles: - Explain reasoning - Be honest about trade-offs standards: code_review: - Every PR needs a "why"

### Platform Team

# platform/.kin name: platform audience: org domains: [engineering] inherits: - ~/.kindex/voices/acme.kin

### Service Repo

# payments-service/.kin name: payments-service audience: team domains: [payments, python] inherits: - ../platform/.kin

The payments service gets: `domains: [payments, python, engineering]`, Acme's voice principles, the platform's review standards, and `audience: team` (local wins). Parent directories are auto-walked when no explicit `inherits` is set. Example voice files included.

## Integrations

### GitHub

Ingest issues, PRs, and commits via `gh` CLI.

### Linear

Ingest issues via GraphQL API.

### Git Hooks

Post-commit records. Pre-push surfaces constraints.

### File Watcher

SHA-256 change detection for registered files.

## CLI Reference

42 commands organized by function. All support `--data-dir`, `--config`, and `--json` flags.

### Core

`kin search <query>` | Hybrid FTS5 + graph search with RRF merging
`kin context` | Formatted context block for AI injection (--level, --tokens)
`kin add <text>` | Quick capture with auto-extraction and linking
`kin show <id>` | Full node details with edges, provenance, and state
`kin list` | List nodes (--type, --status, --mine, --limit)
`kin ask <question>` | Question classification + LLM or context answer

### Knowledge Management

`kin learn` | Extract knowledge from sessions and inbox
`kin link <a> <b>` | Create weighted edge between nodes
`kin alias <id>` | Manage AKA/synonyms for a node
`kin register <id> <path>` | Associate a file path with a node
`kin orphans` | Nodes with no connections
`kin trail <id>` | Temporal history and provenance chain
`kin decay` | Apply weight decay to stale nodes/edges
`kin recent` | Recently active nodes

### Graph Analytics

`kin graph [mode]` | Dashboard: stats, centrality, communities, bridges, trailheads
`kin suggest` | Bridge opportunity suggestions (--accept, --reject)
`kin skills [person]` | Skill profile and expertise for a person
`kin embed` | Index all nodes for vector similarity search

### Operational

`kin status` | Graph health + operational summary (--trigger, --owner)
`kin set-audience <id>` | Set privacy scope (private/team/org/public)
`kin set-state <id> <k> <v>` | Set mutable state on directives/watches
`kin export` | Audience-aware graph export with PII stripping
`kin import <file>` | Import nodes/edges from JSON/JSONL
`kin sync-links` | Update node content with connection references

### Ingestion

`kin ingest <source>` | Ingest from: projects, sessions, files, commits, github, linear, all
`kin cron` | One-shot maintenance cycle (for crontab/launchd)
`kin watch` | Watch for new sessions and ingest (--interval)
`kin analytics` | Archive session analytics and activity heatmap
`kin index` | Write .kin/index.json for git tracking

### Infrastructure

`kin init` | Initialize data directory
`kin config [show|get|set]` | View or edit configuration
`kin setup-hooks` | Install lifecycle hooks into Claude Code
`kin setup-cron` | Install periodic maintenance (launchd/crontab)
`kin doctor` | Health check with graph enforcement
`kin migrate` | Import markdown topics into SQLite
`kin budget` | LLM spend tracking
`kin whoami` | Show current user identity
`kin changelog` | What changed (--since, --days, --actor)
`kin log` | Recent activity log
`kin git-hook` | Install/uninstall git hooks in a repository
`kin prime` | Generate context for SessionStart hook (--codebook)
`kin compact-hook` | Pre-compact knowledge capture