{
  "markdown": "# Kindex\n\n[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)\n[![MIT License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)\n[![v0.36.0](https://img.shields.io/badge/version-0.36.0-purple.svg)](https://github.com/jmcentire/kindex/releases)\n[![PyPI](https://img.shields.io/pypi/v/kindex.svg)](https://pypi.org/project/kindex/)\n[![MCP Market](https://img.shields.io/badge/MCP%20Market-kindex-blue.svg)](https://mcpmarket.com/server/kindex)\n[![Tests](https://github.com/jmcentire/kindex/actions/workflows/workflow.yml/badge.svg)](https://github.com/jmcentire/kindex/actions/workflows/workflow.yml)\n[![MCP Plugin](https://img.shields.io/badge/MCP-Plugin-orange.svg)](#install-as-agent-mcp-plugin)\n\n**The memory layer AI coding agents don't have.**\n\nKindex does one thing. It knows what you know.\n\nIt's a persistent knowledge graph for AI-assisted workflows. It indexes your conversations, projects, and intellectual work so that Claude Code, Codex, Gemini CLI, Google Antigravity, OpenCode, Cursor, and other MCP-capable agents never start a session blind. Available as a **free MCP plugin** or standalone CLI.\n\n> **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.\n\nDocs: [kindex.tools](https://kindex.tools/) is the canonical public site, served by the companion Fly static app. This repo also publishes its `docs/` directory at [jmcentire.github.io/kindex](https://jmcentire.github.io/kindex/). Human setup lives in [docs/human-guide.md](docs/human-guide.md); agent operating rules live in [docs/mcp-agent-guide.md](docs/mcp-agent-guide.md).\n\n## Install\n\nPick whichever installer you already use. They all install the same `kin` and `kin-mcp` binaries.\n\n```bash\n# pip\npip install 'kindex[mcp]'\n\n# uv (single binary, no virtualenv)\nuv tool install 'kindex[mcp]'\n\n# uvx (no install — runs from cache, useful for one-off MCP invocation)\nuvx --from 'kindex[mcp]' kin-mcp --help\n\n# from source\ngit clone https://github.com/jmcentire/kindex && cd kindex && make install\n```\n\n### Upgrading to v0.36.0\n\n> [!WARNING]\n> Before upgrading, stop every Kindex daemon, MCP server, and older CLI\n> process. A v0.35.x process does not reject schema v12 and can write\n> non-canonical session paths after migration.\n\nDream is Kindex's background knowledge-consolidation pass: it finds related\nnodes, safely merges strong duplicates, and stages weaker links for review.\nThe first v0.36.0 process to open an older graph creates a transaction-safe\npre-migration snapshot under\n`$XDG_STATE_HOME/kindex/snapshots/<db>-<hash>/migrations/` (defaulting below\n`~/.local/state/kindex/snapshots/`) before atomically migrating schema v11 to\nv12. The owner-private snapshot passes SQLite integrity and source-version\nchecks, and a partial file is deleted if creation or validation fails.\nConcurrent v0.36+ processes serialize this step through a dedicated\nrollback-journal SQLite lock and recheck the schema after waiting. Migration\nrecovery points are retained outside the rotating ten-file\nautomated-merge snapshot pool. Older duplicate active session tags become paused\nhistory, one active tag per normalized project and name is enforced, and Dream\nsuggestions carry an explicit title-or-node-ID identity contract and title\nambiguity is refused. No node or edge rows are deleted; legacy\ndomain-co-membership edges remain available as stored history but no longer\nparticipate in semantic traversal or health metrics. `kin status` exposes the\ndurably recorded recovery path; normal stores also record it in `kin changelog`.\n\n#### Rolling back the schema migration\n\nDo not open the migrated database with v0.35.x: that version has no\nforward-schema guard and can write old, non-canonical session identity. Instead:\n\n1. While v0.36 is still installed, run `kin status` and record the `Recovery`\n   path. It names the latest validated migration attempt; older attempts remain\n   in the same `migrations/` directory.\n2. Stop every Kindex process again.\n3. Move the live database's `-wal` and `-shm` sidecars aside.\n4. Copy the recorded snapshot over the live database.\n5. Only then install or run v0.35.x and verify the graph.\n\nThis differs from [recovering a bad automated merge](docs/human-guide.md#recover-from-a-bad-automated-merge),\nwhich does not change package versions. Graph-health consumers must also\nrecalibrate: existing node/edge/orphan/component outputs now describe the\nsemantic graph, while explicit stored counts expose retained lifecycle and\nlegacy rows. Machine-readable stats identify this contract as `metrics_schema: 2`.\n\nThen initialize the graph:\n\n```bash\nkin init\n```\n\nExtras — combine in one install (`'kindex[mcp,llm,reminders]'`) or use `'kindex[all]'`:\n\n| Extra | Adds |\n|-------|------|\n| `mcp` | `kin-mcp` MCP server (for Claude Code, Codex, Gemini, Antigravity, OpenCode, Cursor, etc.) |\n| `llm` | Anthropic-powered extraction (`kin learn`, `kin ask`) |\n| `vectors` | sqlite-vec for semantic similarity search |\n| `reminders` | Natural-language time parsing for `kin remind` |\n| `all` | Everything above |\n\n> Homebrew and apt packages aren't published yet. Use `pip`, `uv tool`, `uvx`, or source until they are.\n\n## Install as Agent MCP Plugin\n\nEach 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.\n\n### Claude Code\n\n```bash\nclaude mcp add --scope user --transport stdio kindex -- kin-mcp\nkin init\n```\n\nOr add `.mcp.json` to any repo for project-scope access:\n```json\n{ \"mcpServers\": { \"kindex\": { \"command\": \"kin-mcp\" } } }\n```\n\nThe 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.\n\nFor coding agents, install both the MCP server and the instruction file. The\ninstruction file tells the model how to use kindex: start a session tag, read\ntracked `.kin/config`, check project policy, search before adding, capture\ndurable decisions, and end the tag with a summary.\n\n### Codex\n\n```bash\nkin setup-codex-mcp\nkin setup-codex-hooks\nkin setup-agents-md --install --global\nkin ingest codex-sessions   # optional: backfill saved Codex sessions\n```\n\n`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.\n\nOr hand-edit `~/.codex/config.toml`:\n```toml\n[mcp_servers.kindex]\ncommand = \"kin-mcp\"\n```\n\n### Gemini CLI\n\n```bash\nkin setup-gemini-mcp\nkin setup-gemini-md --install\n```\n\nOr hand-edit `~/.gemini/settings.json`:\n```json\n{ \"mcpServers\": { \"kindex\": { \"command\": \"kin-mcp\", \"args\": [] } } }\n```\n\n### Google Antigravity\n\n```bash\nkin setup-antigravity-mcp\nkin setup-antigravity-hooks\nkin setup-antigravity-md --install\n```\n\n`setup-antigravity-mcp` writes the standalone MCP config shape used by\nAntigravity's editor/shared config and CLI config. `setup-antigravity-hooks`\ninstalls PreInvocation priming/prompt checks, PreToolUse advisory attention and\npermission gating for Kindex config writes, and Stop-time reinforcement enqueue.\n\nOr hand-edit `~/.gemini/config/mcp_config.json` and\n`~/.gemini/antigravity-cli/mcp_config.json`:\n```json\n{ \"mcpServers\": { \"kindex\": { \"command\": \"kin-mcp\", \"args\": [] } } }\n```\n\n### OpenCode\n\n```bash\nkin setup-opencode-mcp\nkin setup-agents-md --install --global\n```\n\nOr hand-edit `~/.config/opencode/opencode.json`:\n```json\n{\n  \"$schema\": \"https://opencode.ai/config.json\",\n  \"mcp\": {\n    \"kindex\": { \"type\": \"local\", \"command\": [\"kin-mcp\"], \"enabled\": true }\n  }\n}\n```\n\nOpenCode reads `AGENTS.md` natively, so install the MCP server and the shared `AGENTS.md` instructions together.\nOpenCode also supports plugins, but Kindex currently uses MCP + instructions there rather than prompt-time attention injection.\n\n### Cursor\n\n```bash\nkin setup-cursor-mcp\nkin setup-cursor-rules --install   # writes ~/.cursor/rules/kindex.mdc\n```\n\nOr hand-edit `~/.cursor/mcp.json`:\n```json\n{ \"mcpServers\": { \"kindex\": { \"type\": \"stdio\", \"command\": \"kin-mcp\" } } }\n```\n\nCursor 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.\n\n## Why Kindex\n\n### Context-aware by design\nFive 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.**\n\n| Tier | Budget | Use Case |\n|------|--------|----------|\n| full | ~4000 tokens | Session start, deep work |\n| abridged | ~1500 tokens | Mid-session reference |\n| summarized | ~750 tokens | Quick orientation |\n| executive | ~200 tokens | Post-compaction re-injection |\n| index | ~100 tokens | Existence check only |\n\n### Knowledge graph, not log file\nNodes have types, weights, domains, and audiences. Edges carry provenance and decay over time. The graph understands what matters — not just what was said.\n\n### Operational guardrails\nConstraints block deploys. Directives encode preferences. Watches flag attention items. Checkpoints run pre-flight. No other memory plugin has this.\n\n### Cache-optimized LLM retrieval\nThree-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.\n\n### Team and org ready\n`.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.\n\n## In Practice\n\nA 162-file fantasy novel vault — characters, locations, magic systems, plot outlines — ingested in one pass. Cross-referenced by content mentions. Searched in milliseconds.\n\n```\n$ kin status\nNodes:     192\nEdges:     11,802\nOrphans:   3\n\n$ time kin search \"the Baker\"\n# Kindex: 10 results for \"the Baker\"\n\n## [document] The Baker - Hessa's Profile and Message Broker System (w=0.70)\n  → Thieves Guild, Five Marks, Thieves Guild Operations\n\n## [person] Mia and The Baker (Hessa) -- Relationship (w=0.70)\n  → Sebastian and Mia, Mia -- Motivations and Goals\n\n0.142 total\n\n$ kin graph stats\nNodes:      192\nEdges:      11,802\nDensity:    0.3218\nComponents: 5\nAvg degree: 122.94\n```\n\n192 nodes. 11,802 edges. 5 context tiers. Hybrid FTS5 + graph traversal in 142ms.\n\n## Getting Agents to Actually Use It\n\nInstalling 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](docs/mcp-agent-guide.md).\n\n```bash\n# Claude Code\nkin setup-claude-md --install\n\n# Codex (and OpenCode — both honor AGENTS.md)\nkin setup-agents-md --install --global\n\n# Gemini CLI\nkin setup-gemini-md --install\n\n# Google Antigravity\nkin setup-antigravity-md --install\n\n# Cursor — writes ~/.cursor/rules/kindex.mdc with alwaysApply: true\nkin setup-cursor-rules --install\n```\n\nThis 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.\n\nFor durable work, agents should use Kindex's persistent task and knowledge\nsurfaces rather than host-session-only task state. Use `task_add`, `task_list`,\nand `task_done` for work that must survive the current conversation; search\nbefore adding knowledge; prefer `edit` or `supersede` over duplicate nodes; and\ntreat tracked `.kin` files as shipped project state, not local cache.\nIf the host also exposes session-local task tools, use those only for temporary\nplanning; durable work belongs in Kindex.\n\nThe 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.\n\n### What gets captured\n\nWith the directives active, the agent will:\n- **Search** the graph before starting work and before adding nodes\n- **Add** discoveries, decisions, key files, notable outputs, and new terms as they emerge\n- **Link** related concepts when connections are found\n- **Learn** from long files and outputs via bulk extraction\n- **Tag** sessions to track work context across conversations\n- **Remind** with actions for deferred tasks (shell commands or headless agent wakeups)\n\n### Actionable Reminders\n\nReminders can carry shell commands, natural-language instructions, or a headless\nagent wakeup. When due, the daemon executes them automatically — simple commands\nrun directly, complex Claude tasks launch `claude -p`, Codex wakeups run\n`codex exec`, and OpenCode wakeups run `opencode run`. Wakeups can resume a\nknown host session id, or `last` for the latest session when the host supports\nthat. This starts/resumes a headless turn from Kindex's daemon/cron context; it\ndoes not interrupt an idle TUI unless the host itself exposes a same-thread\nautomation/server wake path. A Stop hook guard can block Claude from exiting when\nactionable reminders are pending, but it is opt-in because Claude displays\nvisible \"Blocked by hook\" output when a Stop hook blocks.\n\nImportant boundary: `remind_create` records the reminder. Something must later\nrun `kin remind check`, `kin remind exec`, `kin cron`, or an installed\n`kin setup-cron` schedule for due reminders to fire. Wake reminders are a\nKindex capability for Codex and OpenCode because those clients expose\nheadless commands; they are not a reentrant scheduler for an already-idle\ninteractive session.\n\nHook-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.\n\n```bash\n# Kill a cloud instance in 1 hour (but download results first)\nkin remind create \"Kill vast.ai instance\" --at \"in 1 hour\" \\\n  --action \"vastai destroy instance 12345\" \\\n  --instructions \"Download results from /workspace/ before killing\"\n\n# Wake a headless Codex or OpenCode turn when due\nkin remind create \"Continue rollout check\" --at \"in 10 minutes\" \\\n  --wake codex --session last --cwd \"$PWD\" \\\n  --instructions \"Check the rollout and fix any new failures.\"\nkin remind create \"Continue OpenCode build\" --at \"in 10 minutes\" \\\n  --wake opencode --session last --cwd \"$PWD\" --wake-agent build \\\n  --instructions \"Continue the build triage.\"\n\n# Chat-scoped or intentionally global hook-visible reminders\nkin remind create \"Deploy checklist\" --at \"tomorrow 9am\" \\\n  --conversation-id \"$CLAUDE_SESSION_ID\" --attention-trigger deploy\nkin remind create \"Monthly billing review\" --at \"next Monday 9am\" --scope global\n\n# Manual trigger\nkin remind exec --reminder-id <id>\n```\n\n### Dream — Knowledge Consolidation\n\nKindex 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.\n\n```bash\n# See exact merge and domain-link proposals (no changes)\nkin dream --dry-run\n\n# Run full consolidation\nkin dream\n\n# Fast path: dedup + suggestions only\nkin dream --lightweight\n\n# Include LLM-powered cluster summarisation\nkin dream --deep\n\n# Fork and return immediately; repeated detached starts are throttled\nkin dream --detach --lightweight\n```\n\nDefault 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.\n\n### Conversation Modes\n\nModes 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.\n\nFive built-in modes: `collaborate`, `code`, `create`, `research`, `chat`. Create custom modes from any session and export them for team sharing (PII-free).\n\n```bash\n# Seed default modes\nkin mode seed\n\n# Activate a mode — outputs the priming artifact\nkin mode activate collaborate\n\n# Create a custom mode\nkin mode create debug-session \\\n  --primer \"We're hunting a bug. Precision over speed...\" \\\n  --boundary \"Show your reasoning chain. Name assumptions.\" \\\n  --permissions \"Speculate about root causes freely.\"\n\n# Export for team sharing (PII-stripped)\nkin mode export collaborate > collaborate.json\n\n# Import a teammate's mode\nkin mode import their-mode.json\n```\n\nModes 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.\n\n## Quick Start\n\n```bash\n# Add knowledge (with optional tags)\nkin add \"Stigmergy is coordination through environmental traces\" --tags biology,coordination\n\n# Search with hybrid FTS5 + graph traversal\nkin search stigmergy\nkin search coordination --tags biology   # filter results by tag\n\n# Ask questions (with automatic classification)\nkin ask \"How does weight decay work?\"\n\n# Get context for AI injection\nkin context --topic stigmergy --level full\n\n# List and filter by tags\nkin list --tags python,ml              # nodes tagged with both\nkin list --type concept --tags ai      # combine type and tag filters\n\n# Track operational rules\nkin add \"Never break the API contract\" --type constraint --trigger pre-deploy --action block\n\n# Check status before deploy\nkin status --trigger pre-deploy\n\n# Ingest from all sources\nkin ingest all\n\n# Session tags — named work context handles\nkin tag start auth-refactor --focus \"OAuth2 flow\" --remaining \"tokens,tests\"\nkin tag segment --focus \"Token storage\" --summary \"Flow design done\"\nkin tag pause auth-refactor --summary \"Waiting for review\"\nkin tag resume auth-refactor   # reactivate and render admission-controlled context\nkin tag end --summary \"All done\"\n\n# After 60 days, `kin cron` step 8 (or `kin archive run`) moves completed,\n# unlinked session tags from the fast graph (the live database) into the slow\n# archive (separate SQLite files searched explicitly). Active, paused, and\n# artifact-linked sessions stay in the fast graph.\nkin archive run\nkin archive list  # warns if an interrupted move left an ID in both stores\nkin archive search auth-refactor\nkin archive restore <session-node-id>\n\n# Reminders — never forget, never nag\nkin remind create \"standup\" --at \"every weekday at 9am\" --priority high\nkin remind create \"reply to Kevin\" --at \"in 30 minutes\" --priority urgent\nkin remind list\nkin remind snooze --reminder-id <id> --duration 1h\nkin remind done --reminder-id <id>\n```\n\n## Trust, Capture Review, and Bounded Resume\n\nKindex keeps automatic extraction separate from durable knowledge. The\npre-compact hook stages review candidates; it does not create graph nodes or\nedges. Inspect and resolve candidates explicitly:\n\n```bash\nkin candidate list --status pending\nkin candidate show <candidate-id>                 # exact untrusted payload + freshness token\nkin candidate accept <candidate-id> \\\n  --review-token <token> --by \"reviewer\" --method \"manual-review\"\nkin candidate reject <candidate-id> --by \"reviewer\" --code not_relevant\nkin candidate prune                               # expire candidates whose TTL elapsed\nkin candidate erase <candidate-id>                # remove any candidate or receipt\n```\n\nThe review token detects changes between show and accept. It is not\nauthentication, authorization, or proof of reviewer identity. Candidate source\ntext is retained only as a SHA-256 digest, and accepted, rejected, or expired\ncandidates are reduced to minimal receipts. Human candidate output is visibly\ndelimited because its content is untrusted.\n\nVerification is also explicit and records asserted local audit text:\n\n```bash\nkin verify <node-id> --by \"reviewer\" --method \"source-check\" \\\n  --valid-at 2026-08-18T12:00:00Z\nkin invalidate <node-id> --by \"reviewer\" --code superseded \\\n  --at 2026-09-01T00:00:00Z\n\n# Ordinary search/context remain legacy-compatible recall.\nkin search deployment\nkin search deployment --trusted-only\nkin context --topic deployment --trusted-only\n```\n\nTrusted-only search/context and `kin tag resume` admit only active, explicitly\nverified, currently valid, non-contradicted knowledge. Resume output includes an\nauthority warning and machine-reason omission counts. Its legacy `--tokens`\noption is an exact UTF-8 byte budget by default; direct library callers can pass\na provider's exact token counter when they require a provider-token guarantee.\nNon-positive resume budgets return no output.\n\n### Referent Binding and Verifiable Staleness\n\nA node can bind the external thing its claim describes — a file, URL, or repo\nstate — with a content digest and two clocks: `asserted_at` (when the claim was\nmade) and `true_of` (when the referent was observed in the digested state).\nStaleness then stops being a heuristic and becomes a measurement:\n\n```bash\n# Bind at capture time (file paths are hashed now; binding implies direct\n# creation, so the exact claim text is what gets bound)\nkin add \"The parser in src/parse.py handles escapes\" --referent src/parse.py\n\n# Re-hash every bound claim; a moved or missing referent demotes the node\n# from trusted recall and lists it as a re-verification candidate\nkin stale\n\n# After confirming a claim still holds for the new state, rebind it\n# (true_of moves to now; the claim is never re-dated)\nkin stale --rebind <node-id>\n```\n\nDetection never deletes or rewrites content: a stale claim stays recallable,\nvisibly marked `[stale-referent]` in search and context output, and drops out\nof `--trusted-only` projections until re-verified. URL and repo-scope bindings\nare recorded with explicit digests (`--referent-digest`) and surfaced but never\nauto-fetched.\n\nKindex also snapshots the SQLite store (rotating, ten per database) before any\nautomated destructive merge, so a false `graph_merge` or dream-cycle merge is\nrecoverable — see the human guide's restore section.\n\nAutomatic candidates expire after seven days by default. Configure a positive\nretention period in global or project config:\n\n```yaml\ncapture:\n  candidate_ttl_days: 7\n```\n\n### Grounded Retrieval — When the Graph Knows Nothing\n\nVector search returns the nearest neighbours for *any* query, however\nunrelated. Without a floor a near-null question still pulls real nodes into an\nagent's context, and the graph can never say \"I don't know.\"\n\nKindex calibrates a similarity floor against your own corpus and reports a\nverdict with every result set:\n\n```bash\n# Measure the null-query similarity distribution and record the floor\nkin embed calibrate\n\n# Inspect the current record without recalibrating\nkin embed calibrate --show\n```\n\nThe floor is never a config value. It is an immutable, versioned record keyed\nby `provider:model` that carries the corpus it was measured against — node\ncount, embedding count, sample size, timestamp — so a floor calibrated when 2%\nof your graph was embedded is *detected* as stale rather than silently trusted.\nConfig holds only the policy:\n\n```yaml\ngrounding:\n  enabled: true\n  enforce: false          # shadow mode: report the verdict, drop nothing\n  floor_percentile: 95.0\n  weak_margin: 1.15\n  recalibrate_coverage_delta: 0.25\n```\n\nVerdicts are `grounded`, `weak`, `ungrounded`, and `uncalibrated` — the last\nkept deliberately distinct, because \"we have no yardstick\" is a different fact\nfrom \"we measured and found nothing.\"\n\n**Shadow mode is the default on purpose.** Enforcing turns a visible,\nself-correcting problem (irrelevant results in context) into a silent one (an\nagent proceeding without knowledge that was actually there). Run it in shadow\nfirst, see what it *would* have dropped, then set `enforce: true`.\n\n### Multi-Hop Reach\n\nGraph expansion honours `--hops`, with per-hop score decay and a mandatory\nbeam. The beam's ordering is total and stable, so traversal is reproducible:\nadding an edge elsewhere in a hub's neighbourhood cannot silently change what a\nquery returns.\n\n```yaml\nranking:\n  hop_decay: 0.5      # a 2-hop neighbour cannot outrank a 1-hop one\n  graph_beam: 200     # required — real graphs have 800+ fan-out hubs\n```\n\n### Extraction Engines\n\nExtraction is an **input**, never an authority. Engine output lands in the\n`capture_candidates` quarantine and never writes nodes or edges directly.\n\n```bash\n# Which engines are available here\nkin extract engines\n\n# Score them against your own corpus\nkin extract eval --engines keyword,llm --limit 200\n```\n\nThe gate is two-part: grounding precision is a floor (don't invent), title\nrecall is the discriminator (actually find what a curator would record). Either\nalone is gameable — an engine that only copies verbatim scores perfect\ngrounding while finding nothing.\n\nAn optional LLM-free deterministic engine is available behind an extra:\n\n```bash\npip install 'kindex[talon]'   # ~2.5 GB — never a core dependency\n```\n\nIt is excluded from `kindex[all]` by design, and degrades to keyword extraction\nwith a warning when absent. Measure it with `kin extract eval` before enabling\nit; an engine that cannot beat regexes on your corpus has not earned the\ninstall size.\n\n## Editing & Superseding\n\nKnowledge changes. Kindex edits are policy-aware: each node type has a mutability class that says how its content may change, so facts stay correctable while history-bearing records stay append-only.\n\n| Class | Node types | What's allowed |\n|-------|-----------|----------------|\n| `editable` | concept, document, artifact, skill, person, project, question | Full in-place edit: title, content, append, tags, intent, expires |\n| `additive` | decision, constraint, directive, checkpoint, watch | History matters — append and expires only; use `supersede` to replace |\n| `managed` | task, session, coordination | Refused — use the dedicated `task`/`tag`/`coord` commands |\n\n```bash\n# In-place edit (editable types) — accepts node id or exact title\nkin edit oauth-flow --title \"OAuth2 + OIDC flow\" --add-tags auth,oidc\n\n# Additive types only grow: append a dated addendum\nkin edit deploy-constraint --append \"Clarified: applies to staging too\"\n\n# Give any node an expiry — expired nodes stop surfacing and get archived\nkin edit conference-notes --expires 2026-09-01\n\n# Replace with history: new node + supersedes edge, old node marked superseded\nkin supersede old-decision \"We now use OIDC trusted publishing\" --reason \"tokens deprecated\"\n```\n\nEvery edit logs per-field value diffs to the activity log, and `kin changelog` renders them:\n\n```\n## Edited (1 nodes)\n  2026-06-11  [concept] OAuth2 + OIDC flow\n      title: OAuth2 flow -> OAuth2 + OIDC flow\n```\n\nEdits re-embed the node for vector search, protect reserved operational state (locks, claims, coordination messages), and refuse to modify a node another agent has locked unless you pass `--force`. The per-type class can be overridden in config with `edit_policy: {document: additive}` if your team wants stricter history.\n\n## Profiles\n\nOne machine, multiple sequestered graphs. Profiles map names to separate data directories so work and personal knowledge never mix — different DBs, different embeddings, different everything.\n\n```yaml\n# ~/.config/kindex/kin.yaml\nprofiles:\n  work:\n    data_dir: ~/.kindex-work\n    roots: [~/Work]\n  personal:\n    data_dir: ~/.kindex\n    roots: [~/Code, ~/Personal]\ndefault_profile: personal\n```\n\nResolution order (first match wins):\n\n1. `--profile <name>` flag\n2. `KIN_PROFILE` environment variable\n3. `profile:` key from the project's `.kin/config` chain\n4. Longest-prefix match of the current directory against profile `roots`\n5. `default_profile`\n6. Legacy single graph — no profiles configured means nothing changes\n\n```bash\nkin profile list                 # configured profiles + file-level stats\nkin profile which                # which profile this invocation resolves to\n# Two-step adoption: first register your existing graph as the default...\nkin profile create personal --data-dir ~/.kindex --roots ~/Code,~/Personal --default\n# ...then add the sequestered one\nkin profile create work --data-dir ~/.kindex-work --roots ~/Work\nkin status                       # shows: Profile: work (via roots)\n```\n\nRegister the existing legacy graph (usually `~/.kindex`) as the default profile *before* creating others: once a default profile exists, sessions outside all roots route to it, and an unregistered legacy graph stops receiving cron maintenance (`kin profile create` warns when this would happen).\n\n**Stamp guard.** Each profile's database is stamped with its profile name on first open. Opening a stamped database under a different profile raises an error instead of silently mixing graphs — a wrong `--data-dir` can't cross-contaminate.\n\n**MCP note.** The MCP server binds its profile once at process start and keeps it for the process lifetime. To switch profiles for an agent, restart its MCP server (or run a second server with `KIN_PROFILE` set in its environment).\n\n`kin cron` runs one maintenance pass per profile and routes session ingestion by roots — sessions whose cwd falls under a profile's roots land in that profile's graph; the default profile takes the unmatched remainder. With no `default_profile`, a final legacy-remainder pass ingests the unmatched sessions into the legacy graph and keeps its maintenance (reminders, decay, dream) running. `kin cron --profile X` pins a single pass and keeps routing active — it only ingests the sessions X owns; a bare `--data-dir` with no resolved profile runs a legacy take-everything pass on exactly that directory. Routing also applies to `kin ingest sessions|codex-sessions`, the MCP `ingest` tool, and `kin watch`. An explicit `--data-dir` that overrides a profile's data_dir never stamps an unstamped database with the active profile.\n\n## Collab\n\nMultiple agents working the same graph can coordinate through conversations with members, read cursors, shared resources, advisory locks, and standing inject messages.\n\n```bash\n# Join a conversation as a member — members get unread tracking\nkin coord join payments-refactor\n\n# Attach a shared resource so members see who holds what\nkin coord attach payments-refactor invoice-schema\n\n# Advisory locks: signal \"I'm working on this\" — edits refuse foreign locks\nkin lock invoice-schema --ttl 60 --note \"migrating columns\"\nkin unlock invoice-schema\n\n# Targeted message — only alice sees it as unread-for-her\nkin coord post payments-refactor \"schema branch is yours\" --to alice@mbp\n\n# Standing inject message — pushed into members' context until cleared\nkin coord inject payments-refactor set \"Don't touch the invoice schema until migration lands\"\nkin coord inject payments-refactor clear\n```\n\n**Agent identity** resolves as `KIN_AGENT_ID` env > `agent_id` in config > `user@shorthost`. `kin whoami` shows both the user and the resolved agent id. Locks, claims, cursors, and message targeting all key off this identity.\n\nMembers see their collabs in the session-start prime block:\n\n```\n### Active collabs\n- **payments-refactor** — 2 unread (focus: Extract billing service)\n  COLLAB MSG: Don't touch the invoice schema until migration lands (from alice@mbp)\n  Locked: invoice-schema (held by alice@mbp)\n  Check the collab: coord_read payments-refactor\n```\n\nNew targeted/broadcast messages and standing injects also surface mid-session through the prompt hook (with a cooldown so they don't nag). Display is configurable:\n\n```yaml\nagent_id: jeremy-laptop        # optional; default user@shorthost\ncollab:\n  enabled: true\n  display: full                # full | minimal (one line per collab) | quiet (no prime block)\n  prompt_cooldown_minutes: 10  # mid-session injection cooldown\n```\n\nLocks are advisory and expire — an expired lock never blocks anyone, and the cron pass sweeps stale locks, conversations, and task claims.\n\n## .kin/ Directory & Inheritance\n\nProjects 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.\n\n```\n~/.kindex/voices/acme.kin             # Org voice (downloadable, public)\n    ^\n    |  inherits\n~/Code/platform/.kin/config           # Platform team context\n    ^\n    |  inherits\n~/Code/payments-service/.kin/config   # Service-specific context\n```\n\n```yaml\n# payments-service/.kin/config\nname: payments-service\naudience: team\ndomains: [payments, python]\ninherits:\n  - ../platform/.kin/config\nwork_policy:\n  require_active_tag: true\n  linear:\n    enabled: true        # opt-in; personal repos leave this false/absent\n    require_issue: true\n    team: ENG\n  git:\n    block_commit_without_tag: true\n    block_commit_without_linear: true\n```\n\nThe `.kin/` directory is the standard location for all kindex project artifacts:\n- `.kin/config` — project metadata (voice, domains, audience, inheritance)\n- `.kin/index.json` — graph snapshot for git tracking\n- `.kin/code-map.json` — repo-relative code map generated by `kin export code-map`\n- `.kin/.gitignore` — ignores local-only runtime state under `.kin/local`, `.kin/cache`, `.kin/tmp`, and `.kin/private`\n\nThese files are meant to ship with the code. Do not ignore the whole `.kin/`\ndirectory in project `.gitignore`; ignore only local/private subdirectories.\nKindex resolves project config from `--project-path`, then `KIN_PROJECT`, then\nthe git worktree root, then the current directory. User config still lives in\n`~/.config/kindex/kin.yaml` and deep-merges below project config, so user\npreferences remain local while the repo's work contract travels with the repo.\nGenerated `.kin/` snapshots use canonical, id-keyed ordering and omit volatile\ntimestamps so repeated exports of unchanged source do not churn Git diffs.\nConcurrent branches merge them without manual conflicts via a structured merge\ndriver that `kin index` registers automatically on first run (or `kin setup-merge`\nto (re)install it in a fresh clone). `.kin/index.json` is then unioned by node id\n(newer `updated_at` wins) and `.kin/code-map.json` by node/edge/layer — lossless\nacross machines (regenerating from one machine's local DB would drop the other\nbranch's nodes), with output byte-identical to a fresh `kin index`. `kin merge-kin`\nis the driver git invokes; repos without it registered fall back to git's default\nmerge. Never hand-resolve a generated `.kin` snapshot.\nTracked `.kin` artifacts must be self-contained and machine-portable: code-map\npaths are repo-relative POSIX paths, and task/report metadata must not point at\n`$HOME`, `/Users/...`, `/tmp/...`, or another developer-local filesystem\nlocation. If a scanner report is needed as evidence for future work, ship a\nrepo-local subset or a durable shared artifact rather than a local pointer.\n\n`kin export code-map` is different from the normal graph export: it projects\ncurrent code structure into a small dashboard- and agent-friendly graph of\nfiles, classes, functions, layers, and code dependencies. Use it when a tool\nneeds the repo's code shape, not the full Kindex knowledge graph.\n\n| Export | Contains | Use case |\n| --- | --- | --- |\n| `kin export` | Audience-scoped Kindex nodes, edges, provenance, and graph metadata | Backup, exchange, or graph-level tooling |\n| `kin export code-map` | Current repo code structure, code dependencies, layers, and repo-relative file paths | Dashboards, code navigation, and agent tooling |\n\nFor code-map output, `src/file.py` is portable; `/Users/alice/repo/src/file.py`\nand `C:\\repo\\src\\file.py` are not.\n\nCode-map path requirements:\n- Output always uses repo-relative POSIX paths, even when the source machine is\n  Windows.\n- Absolute provenance is normalized only when it resolves inside the requested\n  repo root.\n- Outside-root, malformed, or unresolved paths are omitted with a safe warning\n  rather than leaked into the artifact.\n- Archived nodes are excluded by default because the tracked artifact describes\n  current code; API callers can opt into `include_archived=True` for historical\n  analysis.\n\nThe 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.\n\nOld-style `.kin` files (plain YAML) are auto-upgraded to `.kin/config` on first access.\n\nSee [examples/kin-voices/](examples/kin-voices/) for ready-to-use voice templates.\n\n## Architecture\n\n```\nSQLite + FTS5          <- primary store and full-text search\n  nodes: id, title, content, type, weight, audience, domains, extra\n  edges: from_id, to_id, type, weight, provenance\n  fts5:  content synced via triggers\n\nRetrieval pipeline:\n  FTS5 BM25 --+\n  Graph BFS --+-- RRF merge -- tier formatter -- context block\n  (vectors) --+                   |\n      |                   full | abridged | summarized | executive | index\n      |\n  Embedding providers (configurable):\n      voyage-context-4 (contextual chunks) | openai | gemini | local\n\nLLM cache tiers (kin ask):\n  Tier 1: codebook (stable node index)     <- cached @ 10% cost\n  Tier 2: query-relevant context           <- cached per-topic @ 10% cost\n  Tier 3: user question                    <- full price, tiny\n\nReminders:\n  reminders table (SQLite)    <- separate from knowledge graph\n  Time parsing:  dateparser (NL) + dateutil.rrule (recurrence) + cronsim (cron)\n  Channels:      system (macOS) | slack | email | claude (hook) | terminal\n  Daemon:        launchd/cron adaptive interval -> check due -> notify -> auto-snooze\n  Scheduling:    adaptive tiers (>7d=daily, >1d=hourly, >1h=10min, <1h=5min, none=disabled)\n  Actions:       shell commands | claude -p | codex exec | opencode run\n  Stop guard:    blocks session exit when actionable reminders pending\n\nDream (kin dream):\n  Modes:         lightweight (<5s) | full (non-LLM) | deep (claude -p clusters)\n  Triggers:      CLI | cron step 11 | throttled Stop-time detach\n  Dedup:         difflib.SequenceMatcher, 4-char title bucketing, 0.95 merge / 0.85 suggest\n  Consolidation: suggestion auto-apply, bounded domain proposals, cluster summarisation\n  Safety:        no tag-derived edges, overlap dedup, fcntl.flock, protected types\n\nThree integration paths:\n  MCP plugin --> Claude calls tools natively (search, add, learn, remind, ...)\n  CLI hooks  --> SessionStart / PreCompact / Stop lifecycle events\n  Adapters   --> Entry-point discovery for custom ingestion sources\n  Code       --> ctags + cscope + tree-sitter structural analysis\n```\n\n### Node Types\n\n**Knowledge**: concept, document, session, person, project, decision, question, artifact, skill\n\n### Code Intelligence\n\nIngest repository structure with `kin ingest code --directory .`:\n\n- **Module nodes** (artifact) — one per source file with structural summary: classes, public functions, signatures, imports\n- **Symbol nodes** (concept) — one per class/interface/type with method signatures\n- **Edges** — imports (`depends_on`), inheritance (`implements`), containment (`context_of`), call graph (`relates_to`)\n- **Three extraction tiers** — ctags (100+ languages), cscope (C/C++ cross-refs), tree-sitter (AST call graphs)\n- **Resilient fallback** — unsupported or untagged files still become module nodes; available tree-sitter parsers can still enrich those modules, with fallback provenance retained in metadata\n- **Incremental** — file hashing skips unchanged files on re-ingest\n- **Unity projects (opt-in)** — `--unity` (or `code_ingest: {unity: true}` in `.kin/config`) indexes serialized assets (`.unity`, `.prefab`, `.asset`, `.mat`, `.controller`, `.anim`), sniffs text-vs-binary serialization, and attaches each asset's `.meta` GUID so models can resolve GUID-based references; `code_ingest.include_extensions` maps further extensions (e.g. `.shader: Unity Shader`)\n\nCode 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.\n\n**Operational**: constraint (invariants), directive (soft rules), checkpoint (pre-flight), watch (attention flags)\n\n## CLI Reference (70+ commands)\n\n### Core\n| Command | Description |\n|---------|-------------|\n| `kin search <query>` | Hybrid FTS5 + graph search with RRF merging (--tags, --mine, --trusted-only) |\n| `kin context` | Formatted context block for AI injection (--level, --tokens, --trusted-only) |\n| `kin add <text>` | Quick capture with auto-extraction and linking (--tags, --type) |\n| `kin show <id>` | Full node details with edges, provenance, and state |\n| `kin list` | List nodes (--type, --status, --tags, --audience, --mine, --limit) |\n| `kin ask <question>` | Question classification + LLM or context answer |\n\n### Knowledge Management\n| Command | Description |\n|---------|-------------|\n| `kin learn` | Extract knowledge from sessions and inbox |\n| `kin link <a> <b>` | Create weighted edge between nodes |\n| `kin edit <id>` | Policy-aware in-place edit (--title, --content, --append, --add-tags, --expires) |\n| `kin supersede <id> <text>` | Replace a node with a new one, preserving history (--reason) |\n| `kin alias <id> [add\\|remove\\|list]` | Manage AKA/synonyms for a node |\n| `kin register <id> <path>` | Associate a file path with a node |\n| `kin orphans` | Semantic nodes with no semantic connections (sessions excluded) |\n| `kin trail <id>` | Temporal history and provenance chain |\n| `kin decay` | Apply weight decay to stale nodes/edges |\n| `kin recent` | Recently active nodes |\n| `kin tag [action]` | Session tags: start, update, segment, pause, end, resume, list, show |\n| `kin archive [action]` | Search, restore, or run the reversible slow-graph archive |\n| `kin candidate [action]` | Quarantined capture review: list, show, accept, reject, prune, erase |\n| `kin verify <node>` | Assert verification and optional RFC 3339 valid interval |\n| `kin invalidate <node>` | Record asserted invalidation actor, code, and exclusive end time |\n| `kin stale` | Re-hash referent-bound nodes; demote stale ones from trusted recall (--rebind) |\n| `kin remind [action]` | Reminders: create, list, show, snooze, done, cancel, check, exec |\n| `kin mode [action]` | Conversation modes: activate, list, show, create, export, import, seed |\n\n### Graph Analytics\n| Command | Description |\n|---------|-------------|\n| `kin graph [mode]` | Dashboard: stats, centrality, communities, bridges, trailheads |\n| `kin suggest` | Bridge opportunity suggestions (--accept, --reject) |\n| `kin skills [person]` | Skill profile and expertise for a person |\n| `kin embed` | Index nodes for vector similarity search |\n| `kin embed plan/enqueue/reindex/drain/status` | Scoped embedding maintenance for full or gradual reindexing |\n\n`embedding.provider: voyage` uses `voyage-context-4` by default. When the\nconfigured model supports contextual chunk embeddings, Kindex stores stable\noverlapping chunk vectors and aggregates chunk hits back to the parent node. Use\n`kin embed plan --stale --kin ./path/.kin` to estimate a targeted update,\n`kin embed enqueue --stale --tags mea` to trickle selected work through cron, or\n`kin embed reindex --target ./repo --limit 100` for a bounded foreground pass.\nUnsupported providers/models keep the single-vector strategy unless they later\ngain explicit contextual support.\n\n### Operational\n| Command | Description |\n|---------|-------------|\n| `kin status` | Graph health + operational summary (--trigger, --owner, --mine) |\n| `kin set-audience <id> <scope>` | Set privacy scope (private/team/org/public) |\n| `kin set-state <id> <key> <value>` | Set mutable state on directives/watches |\n| `kin export` | Audience-aware graph export with PII stripping |\n| `kin export code-map` | Repo-relative code map for dashboards, code navigation, and agent tooling |\n| `kin import <file>` | Import nodes/edges from JSON/JSONL (--mode merge/replace) |\n| `kin sync-links` | Update node content with connection references |\n\n### Collab & Multi-Agent\n| Command | Description |\n|---------|-------------|\n| `kin coord [action]` | Agent coordination: start, post, read, list, end, join, attach, inject |\n| `kin lock <id>` | Acquire an advisory lock on a node (--ttl, --note, --force) |\n| `kin unlock <id>` | Release an advisory lock (--force for foreign locks) |\n| `kin profile [action]` | Named graph profiles: list, which, create |\n\n### Ingestion & External Sources\n| Command | Description |\n|---------|-------------|\n| `kin ingest <source>` | Ingest from: projects, sessions, codex-sessions, files, commits, github, linear, code, all |\n| `kin cron` | One-shot maintenance cycle (for crontab/launchd) |\n| `kin dream` | Knowledge consolidation: dedup and reviewable link proposals (--deep, --detach) |\n| `kin watch` | Watch for new sessions and ingest them (--interval) |\n| `kin analytics` | Archive session analytics and activity heatmap |\n| `kin index` | Write .kin/index.json for git tracking |\n| `kin merge-kin` | Git merge driver: structured union merge of `.kin` artifacts (invoked by git) |\n\n### Infrastructure\n| Command | Description |\n|---------|-------------|\n| `kin init` | Initialize data directory |\n| `kin config [show\\|get\\|set]` | View or edit configuration |\n| `kin agent-config [show\\|set]` | View or tune per-client/per-instance agent behavior overrides |\n| `kin policy [show\\|check]` | Show or enforce project work policy from `.kin/config` |\n| `kin setup-merge` | Register the `.kin` structured merge driver in the current git repo |\n| `kin setup-hooks` | Install lifecycle hooks into Claude Code |\n| `kin setup-codex-hooks` | Install prompt-time attention hook into Codex |\n| `kin setup-codex-mcp` | Install kindex MCP server into Codex |\n| `kin setup-gemini-mcp` | Install kindex MCP server into Gemini CLI |\n| `kin setup-antigravity-mcp` | Install kindex MCP server into Google Antigravity |\n| `kin setup-antigravity-hooks` | Install lifecycle hooks into Google Antigravity |\n| `kin setup-opencode-mcp` | Install kindex MCP server into OpenCode |\n| `kin setup-cursor-mcp` | Install kindex MCP server into Cursor |\n| `kin setup-cron` | Install periodic maintenance + dedicated reminder-check job (launchd/crontab) |\n| `kin setup-claude-md` | Output/install recommended CLAUDE.md kindex directives |\n| `kin setup-agents-md` | Output/install recommended AGENTS.md kindex directives (Codex, OpenCode) |\n| `kin setup-gemini-md` | Output/install recommended GEMINI.md kindex directives |\n| `kin setup-antigravity-md` | Output/install Antigravity/GEMINI.md kindex directives |\n| `kin setup-cursor-rules` | Output/install recommended Cursor rule (.mdc) for kindex |\n| `kin stop-guard` | Stop hook guard for actionable reminders |\n| `kin doctor` | Health check with graph enforcement (--fix) |\n| `kin migrate` | Import markdown topics into SQLite |\n| `kin budget` | LLM spend tracking |\n| `kin attention` | Toggle/check/estimate conversation-attention reminder injection |\n| `kin attention-hook` | Advisory attention hook for prompt/tool events |\n| `kin whoami` | Show current user identity |\n| `kin changelog` | What changed (--since, --days, --actor) |\n| `kin log` | Recent activity log |\n| `kin git-hook [install\\|uninstall]` | Manage git hooks in a repository |\n| `kin prime` | Generate context for SessionStart hook (--codebook) |\n| `kin compact-hook` | Pre-compact knowledge capture |\n\n## Configuration\n\nConfig 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.\n\n| Layer | Path | Purpose |\n|-------|------|---------|\n| Global | `~/.config/kindex/kin.yaml` | User-wide defaults |\n| Local | `.kin/config` or `kin.yaml` at project root | Project-specific overrides shipped with code |\n\nUse `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.\n\nAgent-facing behavior can be tuned at three levels:\n\n```bash\n# Global/project default for every client\nkin config set attention.tick_interval 3\n\n# Client default, e.g. every Claude session\nkin agent-config set attention.tick_interval 2 --client claude\n\n# One instance/conversation\nkin agent-config set hooks.prime_tokens 1200 --client claude --scope instance --instance session-a\n```\n\n`agent-config` writes only approved behavior keys such as `attention.*`,\n`sim.*`, `collab.prompt_cooldown_minutes`, and `hooks.prime_tokens`; it cannot\nchange storage paths or arbitrary config. Agents should propose these changes\nthrough their normal tool/command permission flow. Antigravity hooks force a user\npermission prompt before `kin config set` or `kin agent-config set` runs.\n\n```yaml\nagents:\n  clients:\n    claude:\n      attention:\n        tick_interval: 2\n        display: quiet\n  instances:\n    claude:session-a:\n      client: claude\n      attention:\n        tick_interval: 1\n      hooks:\n        prime_tokens: 1200\n```\n\n```yaml\ndata_dir: ~/.kindex\n\nllm:\n  enabled: false\n  provider: anthropic             # anthropic or openai\n  model: claude-haiku-4-5-20251001\n  api_key_env: ANTHROPIC_API_KEY   # comma-separated fallback allowed\n  cache_control: true              # Prompt caching (90% savings on repeated prefixes)\n  codebook_min_weight: 0.5         # Min node weight for codebook inclusion\n  tier2_max_tokens: 4000           # Token budget for query-relevant context\n\nembedding:\n  provider: voyage                 # voyage, openai, gemini, or local\n  # model: \"\"                      # empty = provider default (voyage-context-4 for Voyage)\n  # api_key_env: \"\"                # empty = provider default (VOYAGE_API_KEY / OPENAI_API_KEY / GEMINI_API_KEY)\n  # dimensions: 0                  # 0 = provider default (1024 / 1536 / 3072 / 384)\n  # strategy: \"\"                   # empty/auto; contextual only when the model supports it\n  # chunk_chars: 6000              # stable local chunks for contextual embedding models\n  # chunk_overlap_chars: 600\n  # max_group_chunks: 20\n  # reindex_max_jobs: 200          # cron drain cap for queued embedding work\n  # reindex_max_queue: 100000\n\nbudget:\n  daily: 0.50\n  weekly: 2.00\n  monthly: 5.00\n\ncapture:\n  candidate_ttl_days: 7          # positive TTL for quarantined automatic captures\n\nattention:\n  enabled: false                  # default; runtime override with `kin attention on/off`\n  tick_interval: 3                # run every N prompt-check ticks\n  max_candidates: 6               # deterministic prefilter size before LLM judge\n  max_check_cost: 0.01            # estimated per-check cap\n  max_conversation_cost: 0.25     # best-effort cap when the client provides a stable session id\n  cooldown_seconds: 1800          # suppress repeat injections\n\nproject_dirs:\n  - ~/Code\n  - ~/Personal\n\ndefaults:\n  hops: 2\n  min_weight: 0.1\n  mode: bfs\n\nreminders:\n  enabled: true\n  check_interval: 300            # 5 min base interval\n  adaptive_scheduling: true      # adjust interval based on nearest reminder\n  min_interval: 300              # floor for adaptive scheduling\n  default_channels: [system]     # system, slack, email, claude, terminal\n  snooze_duration: 900           # 15 min default snooze\n  auto_snooze_timeout: 300       # auto-snooze after 5 min inaction\n  idle_suppress_after: 600       # suppress if idle > 10 min\n  stop_guard_enabled: false      # opt-in; blocking Stop hooks are noisy in Claude\n  dream_on_stop_enabled: true    # launch throttled detached dream from Claude Stop hook\n  dream_min_interval: 3600       # seconds between scheduled/hook dream starts\n  dream_max_domain_link_suggestions: 50 # pending domain-review cap per graph\n  channels:\n    slack:\n      enabled: false\n      webhook_url: \"\"\n    email:\n      enabled: false\n      smtp_host: \"\"\n      to_addr: \"\"\n```\n\nUse `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.\n\n## Development\n\n```bash\nmake dev          # install with dev + LLM dependencies\nmake test         # run the full test suite\nmake check        # lint + test combined\nmake clean        # remove build artifacts\n```\n\n## License\n\nMIT\n\n<!-- mcp-name: io.github.jmcentire/kindex -->\n",
  "bytes": 54545,
  "sha": "96fed725ba1faa39a306ddbd4c17df72bee51669594ff8cbac20dea01fbd741d",
  "repo_slug": "jmcentire/kindex",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_jmcentire_kindex_kindex_e06667bb/readme"
}