kindex 0.21.0

The memory layer Claude Code doesn't have — persistent knowledge graph for AI workflows

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

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

Then initialize the graph:

kin init

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

Extra	Adds
mcp	kin-mcp MCP server (for Claude Code, Codex, Gemini, OpenCode, Cursor, etc.)
llm	Anthropic-powered extraction (kin learn, kin ask)
vectors	sqlite-vec for semantic similarity search
reminders	Natural-language time parsing for kin remind
all	Everything above

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

Claude Code now has 30+ native tools: search, add, context, show, ask, learn, link, list_nodes, status, suggest, graph_stats, graph_merge, dream, changelog, ingest, tag_start, tag_update, tag_resume, task_claim, coord_*, 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

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": [] } } }

OpenCode

kin setup-opencode-mcp

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 kin setup-agents-md --install works for OpenCode too. 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.

Tier	Budget	Use Case
full	~4000 tokens	Session start, deep work
abridged	~1500 tokens	Mid-session reference
summarized	~750 tokens	Quick orientation
executive	~200 tokens	Post-compaction re-injection
index	~100 tokens	Existence check only

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 (codebook) is cached at 10% cost. Query-relevant context is predicted via graph expansion and cached per-topic. Only the question pays full price. Transparent — kin ask just works better and cheaper.

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

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

The SessionStart hook (kin setup-hooks) reinforces these directives at the start of every session with a "Session directives" block that reminds Claude 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 Claude invocations)

Actionable Reminders

Reminders can carry shell commands and/or natural-language instructions. When due, the daemon executes them automatically — simple commands run directly, complex tasks launch headless claude -p. 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.

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"

# 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 pending suggestions, and strengthen edges between nodes that share domains. Like memory consolidation during sleep — replay, strengthen important paths, prune noise.

# See what would happen (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
kin dream --detach --lightweight

Default triggers are manual CLI and periodic cron (step 11 of kin cron). File locking prevents concurrent cycles. Stop-time detached dream is opt-in via reminders.dream_on_stop_enabled: true because it can be CPU-heavy on the hook path.

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 deploy
kin status --trigger pre-deploy

# Ingest from all sources
kin ingest all

# Session tags — named work context handles
kin tag start auth-refactor --focus "OAuth2 flow" --remaining "tokens,tests"
kin tag segment --focus "Token storage" --summary "Flow design done"
kin tag resume auth-refactor   # context block for new session
kin tag end --summary "All done"

# Reminders — never forget, never nag
kin remind create "standup" --at "every weekday at 9am" --priority high
kin remind create "reply to Kevin" --at "in 30 minutes" --priority urgent
kin remind list
kin remind snooze --reminder-id <id> --duration 1h
kin remind done --reminder-id <id>

.kin/ Directory & Inheritance

Projects use .kin/ directories that encode their communication style, engineering standards, and values. Teams inherit from orgs. Repos inherit from teams. The knowledge graph carries the voice forward.

~/.kindex/voices/acme.kin             # Org voice (downloadable, public)
    ^
    |  inherits
~/Code/platform/.kin/config           # Platform team context
    ^
    |  inherits
~/Code/payments-service/.kin/config   # Service-specific context

# payments-service/.kin/config
name: payments-service
audience: team
domains: [payments, python]
inherits:
  - ../platform/.kin/config
work_policy:
  require_active_tag: true
  linear:
    enabled: true        # opt-in; personal repos leave this false/absent
    require_issue: true
    team: ENG
  git:
    block_commit_without_tag: true
    block_commit_without_linear: true

The .kin/ directory is the standard location for all kindex project artifacts:

• .kin/config — project metadata (voice, domains, audience, inheritance)
• .kin/index.json — graph snapshot for git tracking
• .kin/.gitignore — ignores local-only runtime state under .kin/local, .kin/cache, .kin/tmp, and .kin/private

These files are meant to ship with the code. Do not ignore the whole .kin/ directory in project .gitignore; ignore only local/private subdirectories. Kindex resolves project config from --project-path, then KIN_PROJECT, then the git worktree root, then the current directory. User config still lives in ~/.config/kindex/kin.yaml and deep-merges below project config, so user preferences remain local while the repo's work contract travels with the repo.

The payments service gets Acme's voice principles, the platform's engineering standards, AND its own domain context. Local values override ancestors. Lists merge with dedup. Parent directories auto-walk when no explicit inherits is set.

Old-style .kin files (plain YAML) are auto-upgraded to .kin/config on first access.

See examples/kin-voices/ for ready-to-use voice templates.

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
      |
  Embedding providers (configurable):
      local (sentence-transformers) | openai | gemini

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

Reminders:
  reminders table (SQLite)    <- separate from knowledge graph
  Time parsing:  dateparser (NL) + dateutil.rrule (recurrence) + cronsim (cron)
  Channels:      system (macOS) | slack | email | claude (hook) | terminal
  Daemon:        launchd/cron adaptive interval -> check due -> notify -> auto-snooze
  Scheduling:    adaptive tiers (>7d=daily, >1d=hourly, >1h=10min, <1h=5min, none=disabled)
  Actions:       shell commands run directly | complex tasks launch claude -p
  Stop guard:    blocks session exit when actionable reminders pending

Dream (kin dream):
  Modes:         lightweight (<5s) | full (non-LLM) | deep (claude -p clusters)
  Triggers:      CLI | cron step 11 | optional Stop-time detach
  Dedup:         difflib.SequenceMatcher, 4-char title bucketing, 0.95 merge / 0.85 suggest
  Consolidation: suggestion auto-apply, domain edge strengthening, cluster summarisation
  Safety:        fcntl.flock exclusion, protected types skip, provenance tracking

Three integration paths:
  MCP plugin --> Claude calls tools natively (search, add, learn, remind, ...)
  CLI hooks  --> SessionStart / PreCompact / Stop lifecycle events
  Adapters   --> Entry-point discovery for custom ingestion sources
  Code       --> ctags + cscope + tree-sitter structural analysis

Node Types

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

Code Intelligence

Ingest repository structure with kin ingest code --directory .:

• Module nodes (artifact) — one per source file with structural summary: classes, public functions, signatures, imports
• Symbol nodes (concept) — one per class/interface/type with method signatures
• Edges — imports (depends_on), inheritance (implements), containment (context_of), call graph (relates_to)
• Three extraction tiers — ctags (100+ languages), cscope (C/C++ cross-refs), tree-sitter (AST call graphs)
• Incremental — file hashing skips unchanged files on re-ingest

Code structure lives in the same graph as your decisions, watches, and constraints. Search finds both what calls a function and what broke last time someone changed it.

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

CLI Reference (49 commands)

Core

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

Knowledge Management

Command	Description
kin learn	Extract knowledge from sessions and inbox
kin link <a> <b>	Create weighted edge between nodes
kin alias <id> [add|remove|list]	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
kin tag [action]	Session tags: start, update, segment, pause, end, resume, list, show
kin remind [action]	Reminders: create, list, show, snooze, done, cancel, check, exec
kin mode [action]	Conversation modes: activate, list, show, create, export, import, seed

Graph Analytics

Command	Description
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

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

Ingestion & External Sources

Command	Description
kin ingest <source>	Ingest from: projects, sessions, codex-sessions, files, commits, github, linear, code, all
kin cron	One-shot maintenance cycle (for crontab/launchd)
kin dream	Knowledge consolidation: dedup, suggestions, edge strengthening (--deep, --detach)
kin watch	Watch for new sessions and ingest them (--interval)
kin analytics	Archive session analytics and activity heatmap
kin index	Write .kin/index.json for git tracking

Infrastructure

Command	Description
kin init	Initialize data directory
kin config [show|get|set]	View or edit configuration
kin policy [show|check]	Show or enforce project work policy from .kin/config
kin setup-hooks	Install lifecycle hooks into Claude Code
kin setup-codex-hooks	Install prompt-time attention hook into Codex
kin setup-codex-mcp	Install kindex MCP server into Codex
kin setup-gemini-mcp	Install kindex MCP server into Gemini CLI
kin setup-opencode-mcp	Install kindex MCP server into OpenCode
kin setup-cursor-mcp	Install kindex MCP server into Cursor
kin setup-cron	Install periodic maintenance (launchd/crontab)
kin setup-claude-md	Output/install recommended CLAUDE.md kindex directives
kin setup-agents-md	Output/install recommended AGENTS.md kindex directives (Codex, OpenCode)
kin setup-gemini-md	Output/install recommended GEMINI.md kindex directives
kin setup-cursor-rules	Output/install recommended Cursor rule (.mdc) for kindex
kin stop-guard	Stop hook guard for actionable reminders
kin doctor	Health check with graph enforcement (--fix)
kin migrate	Import markdown topics into SQLite
kin budget	LLM spend tracking
kin attention	Toggle/check/estimate conversation-attention reminder injection
kin attention-hook	Advisory attention hook for prompt/tool events
kin whoami	Show current user identity
kin changelog	What changed (--since, --days, --actor)
kin log	Recent activity log
kin git-hook [install|uninstall]	Manage git hooks in a repository
kin prime	Generate context for SessionStart hook (--codebook)
kin compact-hook	Pre-compact knowledge capture

Configuration

Config is layered like git — global defaults, then global config, then local config. Each layer deep-merges over the previous, so you only set what you want to override.

Layer	Path	Purpose
Global	~/.config/kindex/kin.yaml	User-wide defaults
Local	.kin/config or kin.yaml at project root	Project-specific overrides shipped with code

Use kin config set --global llm.enabled true for global settings, or kin config set llm.model claude-sonnet-4-6 for project-local. Use --project-path /path/to/repo or KIN_PROJECT=/path/to/repo when running from outside the repo.

data_dir: ~/.kindex

llm:
  enabled: false
  provider: anthropic             # anthropic or openai
  model: claude-haiku-4-5-20251001
  api_key_env: ANTHROPIC_API_KEY   # comma-separated fallback allowed
  cache_control: true              # Prompt caching (90% savings on repeated prefixes)
  codebook_min_weight: 0.5         # Min node weight for codebook inclusion
  tier2_max_tokens: 4000           # Token budget for query-relevant context

embedding:
  provider: voyage                 # voyage, openai, gemini, or local
  # model: ""                      # empty = provider default
  # api_key_env: ""                # empty = provider default (VOYAGE_API_KEY / OPENAI_API_KEY / GEMINI_API_KEY)
  # dimensions: 0                  # 0 = provider default (1024 / 1536 / 3072 / 384)

budget:
  daily: 0.50
  weekly: 2.00
  monthly: 5.00

attention:
  enabled: false                  # default; runtime override with `kin attention on/off`
  tick_interval: 3                # run every N prompt-check ticks
  max_candidates: 6               # deterministic prefilter size before LLM judge
  max_check_cost: 0.01            # estimated per-check cap
  max_conversation_cost: 0.25     # best-effort cap when the client provides a stable session id
  cooldown_seconds: 1800          # suppress repeat injections

project_dirs:
  - ~/Code
  - ~/Personal

defaults:
  hops: 2
  min_weight: 0.1
  mode: bfs

reminders:
  enabled: true
  check_interval: 300            # 5 min base interval
  adaptive_scheduling: true      # adjust interval based on nearest reminder
  min_interval: 300              # floor for adaptive scheduling
  default_channels: [system]     # system, slack, email, claude, terminal
  snooze_duration: 900           # 15 min default snooze
  auto_snooze_timeout: 300       # auto-snooze after 5 min inaction
  idle_suppress_after: 600       # suppress if idle > 10 min
  stop_guard_enabled: false      # opt-in; blocking Stop hooks are noisy in Claude
  dream_on_stop_enabled: false   # opt-in; dream can be CPU-heavy on hook path
  channels:
    slack:
      enabled: false
      webhook_url: ""
    email:
      enabled: false
      smtp_host: ""
      to_addr: ""

Use kin attention estimate --messages 1000 to estimate cost over a fixed prompt window. Conversation accounting is retained when a client provides a stable session id. Hook-driven attention does not fall back to cwd as a fake conversation id, because that would cross-pollute two chats open in the same repo.

Development

make dev          # install with dev + LLM dependencies
make test         # run 980 tests
make check        # lint + test combined
make clean        # remove build artifacts

License

MIT