Kindex

Kindex

每个 Agent 在自己的孤岛中都很聪明。Kindex 让它们协同工作。

Kindex 只做一件事：了解你所知道的。

Claude Code、Codex、Gemini CLI、Google Antigravity、OpenCode、Cursor 和其他支持 MCP 的 Agent 各自保存自己的记忆，彼此却无法读取对方的信息。Kindex 是它们共同读写的本地知识图谱：它能在会话和重启之间保持连续性，在不同厂商之间交接工作，共享决策和约束，并在多个 Agent 同时工作时实时协调。可作为免费 MCP 插件或独立命令行工具使用。

**记忆插件记录发生了什么。Kindex 记录其含义及其关联。**大多数记忆工具都是带搜索功能的会话归档。Kindex 则是加权知识图谱，包含带类型的节点、来源信息和衰减机制，可呈现约束和决策，并根据可用的令牌预算，精确控制注入多少上下文。

Kindex 是个人和代码库的索引：你自己的图谱，以及由 Git 跟踪的仓库 .kin/。Kinbase 是基于 Kindex 的公司级产品，目前正在开发中：它管理工程方向、架构、标准、所有权和历史记录，由具名负责人维护，并整合到每个编码会话中。它们使用相同的引擎和协议，但存储在物理隔离的位置。

文档：kindex.tools 是官方公开网站，由配套的 Fly 静态应用提供服务。此仓库也会在 wandercom.github.io/kindex 发布其 docs/ 目录。人工设置指南见 docs/human-guide.md；Agent 操作规则见 docs/mcp-agent-guide.md。

安装

开发预览：Claude 函数钩子与 signet-eval 共存 新增仓库本地的持久任务、在 Kindex 管理的边界处尽量减少密钥暴露， 并提供可单独选择的现代／旧版适配器。默认仍使用兼容的旧版钩子。 现代适配器是一种 Claude Code mod：当宿主的 claude plugin validate 接受该 mod 时，可安装到 Claude Code 2.1.287 或更高版本（最后一次 验证使用的是 2.1.288）。这并不保证所有 Claude 日志都能被编辑，也不代表 已发布 1.0 版本。

选择你已在使用的安装程序即可。它们安装的都是相同的 kin 和 kin-mcp 二进制文件。

# pip
pip install 'kindex[mcp]'

# uv (single binary, no virtualenv)
uv tool install 'kindex[mcp]'

# uvx (no install — runs from cache, useful for one-off MCP invocation)
uvx --from 'kindex[mcp]' kin-mcp --help

# from source
git clone https://github.com/wandercom/kindex && cd kindex && make install

升级到 v0.36.0

警告

升级前，请停止所有 Kindex 守护进程、MCP 服务和旧版 CLI 进程。v0.35.x 进程不会拒绝 schema v12，并且迁移后可能写入 非规范的会话路径。

Dream 是 Kindex 的后台知识整合流程：它会查找相关节点，安全合并高度重复的节点，并将较弱的链接暂存以供审核。 首个打开旧版图谱的 v0.36.0 进程会在原子性地将 schema v11 迁移到 v12 之前，在 $XDG_STATE_HOME/kindex/snapshots/<db>-<hash>/migrations/ 下创建事务安全的迁移前快照（默认位于 ~/.local/state/kindex/snapshots/ 下）。仅所有者可访问的快照会通过 SQLite 完整性和源版本检查；如果创建或验证失败，则会删除不完整文件。 并发的 v0.36+ 进程会通过专用的回滚日志 SQLite 锁串行执行此步骤，并在等待后重新检查 schema。 迁移恢复点保留在轮换的十个文件自动合并快照池之外。较早的重复活动会话标签会变为暂停历史记录，并强制每个规范化项目和名称只能有一个活动标签；Dream 建议会带有明确的标题或节点 ID 身份契约，并拒绝存在歧义的标题。不会删除任何节点或边行；旧版领域共同成员关系边仍作为存储历史保留，但不再参与语义遍历或健康度指标。kin status 会显示已持久记录的恢复路径；常规存储也会在 kin changelog 中记录该路径。

回滚 schema 迁移

不要使用 v0.35.x 打开已迁移的数据库：该版本没有前向 schema 防护，并且可能写入旧的非规范会话标识。请改为：

1. v0.36 仍处于安装状态时，运行 kin status 并记录 Recovery 路径。该路径指向最近一次已验证的迁移尝试；较早的尝试仍保留在同一个 migrations/ 目录中。
2. 再次停止所有 Kindex 进程。
3. 将实时数据库的 -wal 和 -shm 旁文件移到一边。
4. 将记录的快照复制到实时数据库上。
5. 之后再安装或运行 v0.35.x，并验证图谱。

这不同于恢复损坏的自动合并， 后者不会更改软件包版本。图谱健康度的使用方也必须重新校准：现有节点／边／孤立节点／组件输出现在描述的是语义图谱，而明确的存储计数则会显示保留的生命周期行和旧版行。机器可读的统计信息会通过 metrics_schema: 2 标识此契约。

然后初始化图谱：

kin init

附加功能——可在一次安装中组合（'kindex[mcp,llm,reminders]'），或使用 'kindex[all]'：

附加功能	添加内容
mcp	kin-mcp MCP 服务（适用于 Claude Code、Codex、Gemini、Antigravity、OpenCode、Cursor 等）
llm	由 Anthropic 提供支持的提取功能（kin learn、kin ask）
vectors	用于语义相似度搜索的 sqlite-vec
reminders	用于 kin remind 的自然语言时间解析
all	以上全部

Homebrew 和 apt 软件包尚未发布。在此之前，请使用 pip、uv tool、uvx 或源码。

安装为 Agent MCP 插件

每个 Agent 都会从不同的配置文件读取 MCP 服务。kin setup-*-mcp 命令会将正确格式的配置写入正确路径；旁边也提供了手动配置片段，方便你自行编辑文件。

Claude Code

作为插件（一次安装即可获得 MCP 服务、技能和会话钩子）：

claude plugin marketplace add wandercom/kindex
claude plugin install kindex@kindex

或者，在会话中运行 /plugin install kindex --marketplace wandercom/kindex。

插件运行内容：

• MCP 服务（scripts/claude-plugin/kin-mcp）：如果 PATH 中有已安装的 kin-mcp，就运行它，这样服务和 kin CLI 就能共用同一版本和同一数据库。否则，它会通过 uvx --from 'kindex[mcp]==<version>' kin-mcp 运行匹配的 PyPI 版本，这会从 PyPI 下载 kindex 及其依赖，并缓存起来。此操作需要 uv；如果没有 uv 或 kindex，程序会退出并提示安装方法。
• 钩子（hooks/hooks.json，通过 scripts/claude-plugin/kin）：会话开始、提交提示词、工具调用前、压缩前和停止时都会调用已安装的 kin，以预先加载上下文、根据图谱检查提示词并捕获会话。如果没有安装 kin，这些钩子不会执行任何操作。它们会先加载 ~/.profile，以便找到通过 pipx、uv 或 Homebrew 安装的 kin。
• 技能：kindex-prime、kindex-capture、kindex-learn。

所有数据都保留在你的机器上：图谱是本地 SQLite 数据库（~/.kindex/ 和各仓库中的 .kin/）。除非你配置了大模型或嵌入提供方，否则不会向任何地方发送数据（请参阅隐私）。

或者，作为独立的 MCP 服务运行：

claude mcp add --scope user --transport stdio kindex -- kin-mcp
kin init

或者，在任意仓库中添加 .mcp.json，为该项目注册服务：

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

注册范围不会限制图谱访问。如果 Agent 只能使用单个仓库的记忆，请改为运行 kindex-lite --repo /absolute/path/to/repo。它会将 MCP 服务绑定到该仓库的 .kin 图谱和 Kinbase 读取操作，不会回退到全局图谱。Kinbase 提交和写入权限状态需要启动器的 --allow-kinbase-submit；--no-kinbase 则会完全停用 Kinbase。配置方法和隔离边界请参阅绑定仓库的 MCP。

MCP 服务会向受支持的客户端提供 50 多个原生工具：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_* 等。

对于编码 Agent，请同时安装 MCP 服务和指令文件。指令文件会告诉模型如何使用 kindex：启动会话标签、读取受跟踪的 .kin/config、检查项目策略、先搜索再添加、捕获持久决策，并以摘要结束标签。

Codex

kin setup-codex-mcp
kin setup-codex-hooks
kin setup-agents-md --install --global
kin ingest codex-sessions   # optional: backfill saved Codex sessions

setup-codex-hooks 会安装 SessionStart 钩子（以及提示词／工具关注钩子），让 Codex 在每次会话开始时都能像 Claude Code 一样自动预加载上下文，并获得“使用 kindex”／.kin 指令。Codex 只会在你信任新建或更改的钩子后才运行它们；你可以在启动时的审核提示中或 /hooks 中进行信任。在此之前，它不会运行这些钩子，包括 SessionStart。

或者，手动编辑 ~/.codex/config.toml：

[mcp_servers.kindex]
command = "kin-mcp"

Gemini CLI

kin setup-gemini-mcp
kin setup-gemini-md --install

或者，手动编辑 ~/.gemini/settings.json：

{ "mcpServers": { "kindex": { "command": "kin-mcp", "args": [] } } }

Google Antigravity

kin setup-antigravity-mcp
kin setup-antigravity-hooks
kin setup-antigravity-md --install

setup-antigravity-mcp 会写入 Antigravity 编辑器／共享配置和 CLI 配置使用的独立 MCP 配置格式。setup-antigravity-hooks 会安装 PreInvocation 上下文预加载／提示词检查、PreToolUse 提醒关注和针对 Kindex 配置写入的权限控制，以及停止时的强化入队钩子。

或者，手动编辑 ~/.gemini/config/mcp_config.json 和 ~/.gemini/antigravity-cli/mcp_config.json：

{ "mcpServers": { "kindex": { "command": "kin-mcp", "args": [] } } }

Muse

kin setup-muse-mcp

Muse 会读取 ~/.config/muse/settings.json（使用驼峰命名的 mcpServers；切勿添加旧版 mcp_servers 键，否则 Muse 会丢弃所有 MCP 服务）。Muse 已会加载 Claude Code 和 Codex 的个人规则，因此运行 kin setup-agents-md --install --global 即可安装其指令。Muse 不会运行 Claude 或 Codex hooks，Kindex 也尚未安装 Muse 原生 hooks。或者手动编辑：

{ "mcpServers": { "kindex": { "type": "stdio", "command": "/opt/homebrew/bin/kin-mcp", "args": [], "mode": "optional" } } }

OpenCode

kin setup-opencode-mcp
kin setup-opencode-hooks
kin setup-agents-md --install --global

或者手动编辑 ~/.config/opencode/opencode.json：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "kindex": { "type": "local", "command": ["kin-mcp"], "enabled": true }
  }
}

OpenCode 原生读取 AGENTS.md，因此请同时安装 MCP 服务和共享的 AGENTS.md 指令。 OpenCode 插件会在主要用户消息上定期提供监督建议。配置和通知设置请参阅监督与独立健康检查。

Cursor

kin setup-cursor-mcp
kin setup-cursor-hooks
kin setup-cursor-rules --install   # writes ~/.cursor/rules/kindex.mdc

或者手动编辑 ~/.cursor/mcp.json：

{ "mcpServers": { "kindex": { "type": "stdio", "command": "kin-mcp" } } }

Cursor 集成包含 MCP、始终应用的规则和原生监督 hooks。该适配器已通过自动化边界测试；经身份验证的 Cursor 模型交付和 IDE 活动发现仍未经验证。无需 Cursor 账户，也可将 Kindex 与其他受支持的 Agent 搭配使用。请参阅监督与独立健康检查。

远程 Agent（通过 Cloudflare Access 使用 HTTPS）

kindex-remote（额外安装 kindex[remote]）通过可流式传输的 HTTP 向其他机器上的 Agent 提供你的图谱。 它仅监听环回地址；Cloudflare Tunnel 会将其发布出去，而 Cloudflare Access 应用会对每个调用方进行身份验证： 交互式 Agent（Claude Code、Codex、claude.ai 连接器）使用托管 OAuth，无头 Agent 使用服务令牌。服务器还会在每个请求上验证 Access JWT （Cf-Access-Jwt-Assertion：签名、受众、颁发者）。

kindex-remote --access-team-domain <team>.cloudflareaccess.com \
  --access-aud <application AUD tag> --public-host app.example.com --port 8767

仅提供图谱工具（搜索、上下文、添加/编辑/学习/链接、任务、标签、协调、监视、提问）。不会提供运行命令、读取主机路径或从主机导入内容的工具（提醒、导入、模式、维护、Kinbase、task_execute），也不提供 graph_stats。add 仅接受 URL 引用，任务工具会拒绝 project_path，而 show 不会解析已保存的来源。工具调用会在工作线程上逐一运行，不占用请求循环。

交互式 Agent 需要 Access 应用启用动态客户端注册的托管 OAuth（并允许客户端的回调 URL）。使用 claude mcp add --transport http kindex https://app.example.com/mcp 连接一个 Agent（OAuth 会打开一次浏览器）；无头客户端则改为发送 CF-Access-Client-Id 和 CF-Access-Client-Secret 请求头。

为什么选择 Kindex

专为上下文感知而设计

系统会根据可用令牌自动选择五个上下文层级。当其他插件把所有内容都塞进上下文时，Kindex 可以提供 200 个令牌的执行摘要，也可以提供 4000 个令牌的深度上下文——具体取决于可用空间。你的插件不会占用上下文窗口。

层级	预算	使用场景
full	约 4000 个令牌	会话开始、深度工作
abridged	约 1500 个令牌	会话中途参考
summarized	约 750 个令牌	快速了解概况
executive	约 200 个令牌	压缩后重新注入
index	约 100 个令牌	仅检查是否存在

知识图谱，而非日志文件

节点具有类型、权重、领域和受众。边包含来源信息，并会随时间衰减。图谱理解哪些内容重要——而不只是记录说过什么。

运行防护机制

约束会阻止部署。指令会记录偏好。监视会标记需要关注的事项。检查点会执行飞行前检查。其他记忆插件都不具备这些功能。

基于带日期的证据作答

kin ask 通过一次模型调用，基于带日期的证据作答：按时间顺序排列的匹配节点、今天的日期和你的常设指令，并精简到与问题相关的消息；对于单条事实，预算较小；对于计数、列表、排序、摘要和建议，预算则更宽裕。由 kin digest 写入的对话事实和个人档案，让它只需几千个 token 就能作答；证据中的相对日期也已提前解析。若在配置中设置 conversations.claims: true，kin digest 会记录轮次级主张，而不是每段对话的事实；每条主张都关联到其来源消息（在对话中的位置及原文）；kin digest --claims 可转换之前已摘要的对话。在终端中，答案会在生成时实时流式输出。答案规则涵盖已更新的值、跨对话计数、日期计算和缺失细节。kin ingest conversations --directory DIR 会无损存储聊天记录，供它搜索。MCP ask 工具会将相同的带日期证据返回给调用它的 Agent（并通过 answer=true 自行拟写答案）；context(level="evidence") 会返回某个主题的相关证据。

适用于团队和组织

.kin 继承链让服务仓库可以继承平台上下文，而平台上下文又可继承组织语气。私有／团队／组织／公开范围控制，并在导出时剥离 PII。从第一天起即可满足企业需求。

实际应用

一个包含 162 个文件的奇幻小说库——人物、地点、魔法体系、情节大纲——一次性完成导入。根据内容提及进行交叉引用。毫秒级完成搜索。

$ 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 个节点。11,802 条边。5 个上下文层级。混合使用 FTS5 和图遍历，耗时 142ms。

让 Agent 真正使用它

安装 MCP 插件即可为 Agent 提供这些工具。但如果不明确告知，Agent 不会主动使用它们。Kindex 附带推荐的指令块，可将被动工具变成主动习惯。完整的 Agent 操作指南请参阅 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

# Google Antigravity
kin setup-antigravity-md --install

# Cursor — writes ~/.cursor/rules/kindex.mdc with alwaysApply: true
kin setup-cursor-rules --install

这会添加会话生命周期规则（开始／定向／进行中／分段／结束）、明确的记录触发条件（发现、决策、任务、关键文件、重要产出），以及先搜索再添加的准则。「Agent 拥有知识图谱」与「Agent 会主动维护知识图谱」之间的区别，就在于这个指令块。

对于需要持久保存的工作，Agent 应使用 Kindex 的持久任务和知识 功能，而不是仅限于主机端会话的任务状态。对于必须在当前对话结束后 保留的工作，请使用 task_add、task_list 和 task_done；添加知识前 先进行搜索；优先使用 edit 或 supersede，而不是创建重复节点；并且 应将受跟踪的 .kin 文件视为已交付的项目状态，而非本地缓存。 如果主机还提供仅限会话的任务工具，请仅将其用于临时规划；持久工作 应归入 Kindex。

对于仓库中的 MCP 客户端，如果读取操作提供了项目级或全局限定的 引用，请保留这些引用并原样传递给后续工具。在双图会话中，如果新节点 或任务源自现有知识，请在 source_refs 中使用这些限定的证据 ID。普通的 单存储和档案响应仍使用旧式原始 ID；source_refs 不接受这些原始 ID。 重启 MCP 服务后，请再次搜索，因为限定的引用令牌绑定到其存储选择。 有关读取范围和写入路由，请参阅 Profiles。

Claude SessionStart hook（kin setup-hooks）和 Codex hooks（kin setup-codex-hooks）会在受支持会话开始时通过「Session directives」指令块强化这些指令，提醒 Agent 在整个会话期间使用 kindex MCP 工具。

捕获内容

启用这些指令后，Agent 会：

• 搜索：在开始工作前和添加节点前搜索图谱
• 添加：随着发现的进展，添加发现、决策、关键文件、显著输出和新术语
• 链接：发现关联时连接相关概念
• 学习：通过批量提取学习长文件和输出内容
• 标记：为会话添加标签，以便在多个对话中追踪工作上下文
• 提醒：为延期任务创建操作提醒（shell 命令或无头 Agent 唤醒）

可执行提醒

提醒可以包含 shell 命令、自然语言指令或无头 Agent 唤醒。到期时，守护进程会自动执行：简单命令会直接运行，复杂的 Claude 任务会启动 claude -p，Codex 唤醒会运行 codex exec，OpenCode 唤醒会运行 opencode run。唤醒可以恢复已知的主机会话 ID，也可以在主机支持时使用 last 恢复最新会话。这会从 Kindex 的守护进程／cron 上下文启动或恢复一次无头执行；除非主机本身提供同一线程的自动化／服务器唤醒路径，否则不会打断空闲的 TUI。Stop hook 守卫可以在存在待处理的可执行提醒时阻止 Claude 退出，但该功能默认选择关闭，因为 Stop hook 阻止退出时，Claude 会显示可见的“Blocked by hook”输出。

重要限制：remind_create 只会记录提醒。之后必须运行 kin remind check、kin remind exec、kin cron，或安装 kin setup-cron 定时任务，才能触发到期提醒。唤醒提醒是 Kindex 为 Codex 和 OpenCode 提供的功能，因为这些客户端支持无头命令；它不是用于唤醒已空闲交互会话的可重入调度器。

hook 执行时注入提醒会使用范围限定的提醒看板。当客户端提供聊天／会话 ID（conversation_id、chat_id、session_id、CLAUDE_SESSION_ID、CODEX_SESSION_ID、OPENCODE_SESSION_ID、CURSOR_SESSION_ID 等）时，Kindex 只会注入限定于该 ID 的提醒，以及明确标记为 --scope global 的提醒。未限定范围的旧版提醒仍可用于手动运行 kin prompt-check、守护进程检查和通知，但默认不会注入已识别的聊天中。

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

# Wake a headless Codex or OpenCode turn when due
kin remind create "Continue rollout check" --at "in 10 minutes" \
  --wake codex --session last --cwd "$PWD" \
  --instructions "Check the rollout and fix any new failures."
kin remind create "Continue OpenCode build" --at "in 10 minutes" \
  --wake opencode --session last --cwd "$PWD" --wake-agent build \
  --instructions "Continue the build triage."

# 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 — 知识整合

Kindex 可以执行模糊去重、自动应用高置信度的待处理建议，并暂存有范围限制的领域链接提案供审核。已解决的模糊匹配不会再次创建。待处理的领域审核队列按图谱设有上限（默认值为 50，由 reminders.dream_max_domain_link_suggestions 设置），提案会按轮询方式覆盖各个领域，被拒绝的配对会保持拒绝状态。该设置位于 reminders 下，因为定时运行和 Stop hook 触发的 Dream 使用提醒／维护配置。这就像睡眠期间的记忆整合——重放重要路径并清除噪声，而不会把标签转变为拓扑结构。

# See exact merge and domain-link proposals (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; repeated detached starts are throttled
kin dream --detach --lightweight

默认触发方式包括手动 CLI、定期 cron（kin cron 的第 11 步）和经节流处理的分离式 Stop hook。文件锁可防止周期并发运行，reminders.dream_min_interval 可防止 hook 或 cron 在最近一次启动后反复重新启动 dream。将 reminders.dream_on_stop_enabled: false 设为 false，即可禁用 Stop 时的分离式 dream，同时保留手动和 cron dream 功能。

对话模式

模式是可重复使用的对话预设，可在 AI 会话中诱导出特定的处理模式。研究表明，诱导式理解的效果比直接指令高 5.4 倍，而仅用 15 个 token 设置模式，就能获得 98.8% 的可实现预设收益。

内置五种模式：collaborate、code、create、research、chat。可根据任意会话创建自定义模式，并导出供团队共享（不含个人身份信息）。

# 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

模式不是指令，而是状态诱导。预设语句确立思考方式，边界定义质量标准，权限则说明允许做什么。AI 会切换处理模式，而不是照着清单逐项执行。

快速入门

# 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 auth-refactor --focus "Token storage" --summary "Flow design done"
kin tag pause auth-refactor --summary "Waiting for review"
kin tag resume auth-refactor   # reactivate and render admission-controlled context
kin tag end auth-refactor --summary "All done"

# After 60 days, `kin cron` step 8 (or `kin archive run`) moves completed,
# unlinked session tags from the fast graph (the live database) into the slow
# archive (separate SQLite files searched explicitly). Active, paused, and
# artifact-linked sessions stay in the fast graph.
kin archive run
kin archive list  # warns if an interrupted move left an ID in both stores
kin archive search auth-refactor
kin archive restore <session-node-id>

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

信任、捕获审查与有界恢复

Kindex 将自动提取与持久化知识分开处理。pre-compact hook 会暂存待审查候选项；它不会创建图节点或边。请明确检查并处理候选项：

kin candidate list --status pending
kin candidate show <candidate-id>                 # exact untrusted payload + freshness token
kin candidate accept <candidate-id> \
  --review-token <token> --by "reviewer" --method "manual-review"
kin candidate reject <candidate-id> --by "reviewer" --code not_relevant
kin candidate prune                               # expire candidates whose TTL elapsed
kin candidate erase <candidate-id>                # remove any candidate or receipt

审查令牌可检测从显示到接受期间发生的变更。它不用于身份验证、授权，也不能证明审查者身份。候选项的源文本仅保留为 SHA-256 摘要；已接受、已拒绝或已过期的候选项会精简为最少回执。候选项输出会以明显标记分隔，因为其内容不受信任。

验证也必须明确执行，并会记录声明的本地审计文本：

kin verify <node-id> --by "reviewer" --method "source-check" \
  --valid-at 2026-08-18T12:00:00Z
kin invalidate <node-id> --by "reviewer" --code superseded \
  --at 2026-09-01T00:00:00Z

# Ordinary search/context remain legacy-compatible recall.
kin search deployment
kin search deployment --trusted-only
kin context --topic deployment --trusted-only

仅限受信任内容的搜索／上下文以及 kin tag resume 只会纳入处于活动状态、经过明确验证、当前有效且未被反驳的知识。恢复输出包含权限警告和按机器可读原因统计的省略数量。默认情况下，其旧版 --tokens 选项采用精确的 UTF-8 字节预算；直接调用库的用户可传入提供方的精确 token 计数器，以确保符合提供方的 token 限制。恢复预算小于或等于零时不返回任何输出。

指代对象绑定与可验证的过时状态

节点可以绑定其声明所描述的外部对象（文件、URL 或仓库状态），并记录内容摘要和两个时间：asserted_at（声明作出的时间）与 true_of（引用对象处于摘要所示状态的观测时间）。这样一来，过时状态不再是启发式判断，而是可以测量的结果：

# Bind at capture time (file paths are hashed now; binding implies direct
# creation, so the exact claim text is what gets bound)
kin add "The parser in src/parse.py handles escapes" --referent src/parse.py

# Re-hash every bound claim; a moved or missing referent demotes the node
# from trusted recall and lists it as a re-verification candidate
kin stale

# After confirming a claim still holds for the new state, rebind it
# (true_of moves to now; the claim is never re-dated)
kin stale --rebind <node-id>

检测绝不会删除或改写内容：过时声明仍可被检索，在搜索和上下文输出中会以 [stale-referent] 明确标记，并且在重新验证前不会出现在 --trusted-only 投影中。URL 和仓库范围绑定会通过明确的摘要（--referent-digest）记录并展示，但绝不会自动获取。

Kindex 还会在任何自动破坏性合并之前为 SQLite 存储创建快照（每个数据库轮换保留十份），因此可以恢复错误的 graph_merge 或 dream-cycle 合并——请参阅人工指南中的恢复部分。

默认情况下，自动候选项会在七天后过期。可在全局或项目配置中设置大于零的保留期限：

capture:
  candidate_ttl_days: 7

基于事实的检索 — 当图谱一无所知时

向量搜索会为任何查询返回最近邻，无论它们是否相关。没有下限时，即使问题几乎毫无关联，也会将真实节点带入 Agent 的上下文，而图谱永远无法说“我不知道”。

Kindex 会根据你自己的语料校准相似度下限，并为每组结果报告判定：

# Measure the null-query similarity distribution and record the floor
kin embed calibrate

# Inspect the current record without recalibrating
kin embed calibrate --show

下限绝不会是配置值。它是一条不可变、带版本的记录，以 provider:model 为键，并附带校准所依据的语料信息——节点数、嵌入数量、样本量、时间戳——因此，当图谱中只有 2% 完成嵌入时校准的下限会被检测为已过时，而不会被默默信任。配置中只保存策略：

grounding:
  enabled: true
  enforce: false          # shadow mode: report the verdict, drop nothing
  floor_percentile: 95.0
  weak_margin: 1.15
  recalibrate_coverage_delta: 0.25

判定结果为 grounded、weak、ungrounded 和 uncalibrated——最后一种特意单独区分，因为“我们没有衡量标准”与“我们测量过，什么也没找到”是不同的事实。

默认采用影子模式是有意为之。 启用强制执行会将一个可见、可自我纠正的问题（上下文中出现无关结果）变成一个隐蔽问题（Agent 在不知道实际已有相关知识的情况下继续执行）。请先在影子模式下运行，看看它本会丢弃哪些结果，然后再设置 enforce: true。

多跳扩展

图扩展遵循 --hops，并采用逐跳分数衰减和强制 beam。beam 的排序是全序且稳定的，因此遍历结果可复现：即使在某个枢纽节点的邻域其他位置添加边，也不会悄然改变查询结果。

ranking:
  hop_decay: 0.5      # a 2-hop neighbour cannot outrank a 1-hop one
  graph_beam: 200     # required — real graphs have 800+ fan-out hubs

提取引擎

提取结果是输入，绝非权威依据。引擎输出会进入 capture_candidates 隔离区，绝不会直接写入节点或边。

# Which engines are available here
kin extract engines

# Score them against your own corpus
kin extract eval --engines keyword,llm --limit 200

把关分为两部分：事实依据精确度是下限（不得编造），标题召回率是区分标准（确实找到策展人会记录的内容）。单独使用任何一项都可能被钻空子——只复制原文的引擎，事实依据评分可以满分，却什么也找不到。

另有一个可选的无 LLM 确定性引擎，可通过额外项启用：

pip install 'kindex[talon]'   # ~2.5 GB — never a core dependency

它经过设计，不包含在 kindex[all] 中；若不可用，则会发出警告并降级为关键词提取。启用前请用 kin extract eval 对它进行评估；如果某个引擎在你的语料上无法胜过正则表达式，它就不值得占用安装空间。

编辑与取代

知识会变化。Kindex 的编辑会遵循策略：每种节点类型都有一个可变性类别，规定其内容可以如何变化，因此事实可以得到更正，而承载历史的记录则保持只追加。

类别	节点类型	允许的操作
editable	concept、document、artifact、skill、person、project、question	完整的原地编辑：标题、内容、追加、标签、意图、过期时间
additive	decision、constraint、directive、checkpoint、watch	历史很重要——仅允许追加和设置过期时间；请使用 supersede 进行替换
managed	task、session、coordination	拒绝修改——请使用专用的 task/tag/coord 命令

# In-place edit (editable types) — accepts node id or exact title
kin edit oauth-flow --title "OAuth2 + OIDC flow" --add-tags auth,oidc

# Additive types only grow: append a dated addendum
kin edit deploy-constraint --append "Clarified: applies to staging too"

# Give any node an expiry — expired nodes stop surfacing and get archived
kin edit conference-notes --expires 2026-09-01

# Replace with history: new node + supersedes edge, old node marked superseded
kin supersede old-decision "We now use OIDC trusted publishing" --reason "tokens deprecated"

每次编辑都会将逐字段的值差异记录到活动日志中，kin changelog 会将其呈现出来：

## Edited (1 nodes)
  2026-06-11  [concept] OAuth2 + OIDC flow
      title: OAuth2 flow -> OAuth2 + OIDC flow

编辑会为节点重新生成嵌入，以用于向量搜索，保护预留的运行状态（锁、声明、协调消息），并拒绝修改其他 Agent 已锁定的节点，除非你传入 --force。如果团队希望更严格地保留历史记录，可以在配置中覆盖每种类型的类别，例如 edit_policy: {document: additive}。

配置档案

一台机器，多个相互隔离的图谱。配置档案将名称映射到不同的数据目录，让工作知识与个人知识永不混杂——数据库、嵌入及其他所有内容都各不相同。

# ~/.config/kindex/kin.yaml
profiles:
  work:
    data_dir: ~/.kindex-work
    roots: [~/Work]
  personal:
    data_dir: ~/.kindex
    roots: [~/src, ~/notes]
default_profile: personal

解析顺序（以第一个匹配项为准）：

1. --profile <name> 标志
2. KIN_PROFILE 环境变量
3. 项目的 .kin/config 配置链中的 profile: 键
4. 当前目录与配置档案 roots 的最长前缀匹配
5. default_profile
6. 旧版单图谱——未配置配置档案意味着不会有任何变化

kin profile list                 # configured profiles + file-level stats
kin profile which                # which profile this invocation resolves to
# Two-step adoption: first register your existing graph as the default...
kin profile create personal --data-dir ~/.kindex --roots ~/src,~/notes --default
# ...then add the sequestered one
kin profile create work --data-dir ~/.kindex-work --roots ~/Work
kin status                       # shows: Profile: work (via roots)

在创建其他配置文件之前，先将现有的旧版图（通常为 ~/.kindex）注册为默认配置文件：默认配置文件一旦存在，所有不属于任何根目录的会话都会路由到该配置文件，而未注册的旧版图将不再接受 cron 维护（如果会发生这种情况，kin profile create 会发出警告）。

印章保护。 每个配置文件的数据库首次打开时都会盖上该配置文件名称的印章。使用不同的配置文件打开已盖章的数据库会报错，而不会悄悄混合图谱，因此错误的 --data-dir 不会造成数据交叉污染。

MCP 说明。 MCP 服务会在进程启动时绑定其配置文件，并在整个进程生命周期内保持该配置文件不变。要为 Agent 切换配置文件，请重启其 MCP 服务（或使用在其环境中设置了 KIN_PROFILE 的第二个服务）。

如果没有活动配置文件或显式指定存储，则存在的仓库本地 .kin/local 存储会成为选定图谱。自动读取会包含该选定图谱和已配置的用户图谱。search、task_list、context、ask、prime、list_nodes、status、suggest、graph_stats、graph_heal、changelog、watch_list 和 orient 支持 graph="auto"|"project"|"global"。Auto 会查询两个获准的存储；project 只读取选定存储，即使用户图谱不可用也不例外；global 只读取已配置的用户存储。固定资源 kindex://status、kindex://recent 和 kindex://orphans 使用 auto 范围。显式配置文件仍是单一存储边界，并拒绝 global 范围。

双图谱结果会携带 project:<session>:<id> 或 global:<session>:<id> 引用。普通的单存储／配置文件读取会保留原始 ID，以兼容旧版。 在 show、编辑、链接、任务变更和监视项解析时，请保留完整引用。会话令牌会将其绑定到一个 MCP 存储选择；重启或图谱变更后，过期引用将失效。每个图谱的混合搜索会保留自身的排名，两个图谱的结果则按倒数排名交错排列。合并后的排名并非跨数据库校准过的相关性分数。由于边和连通分量不会跨越存储，诊断信息会分别显示各图谱的部分。

不带来源的 add、learn、task_add 和 watch_add 会写入选定存储（存在仓库时选定的存储为项目图谱）。在双图谱会话中，设置 graph="global" 可显式写入外部存储；或者在 source_refs 中传入当前带图谱限定的证据 ID，以路由派生写入：只要有一个来源属于 global，混合项目／global 证据就会路由到用户图谱。source_refs 不接受不带限定的 ID。link_to 只有在裸标题或 ID 能唯一解析时才可接受；创建前会拒绝跨存储链接，且 Kindex 不会创建跨存储边。路由到用户图谱的上下文 task_add 若省略 project_path，会继承已绑定的选定项目路径，以便默认的 task_list 找到该任务。显式项目路径优先；scope="global" 则始终全局可见，不会推断项目关联。协调、模式、会话标签和其他仅针对选定存储的操作工具不会因此获得全局变更模式。仓库和分支名称是相关性上下文，而非写入其他工作树图谱的授权依据。

只有当选定存储是该仓库自身的规范 .kin/local 或声明的本地存储时，仓库的 edit_policy 才适用。显式配置文件和用户／全局存储仍遵循用户的编辑策略，即使其数据目录恰好位于仓库目录树内也是如此。

这些引用有意限定于会话范围，并非持久图谱标识符。若要进行更广泛的图谱发现，需要持久数据库身份，并将其绑定到已配置的全局位置或活动工作树。仓库身份可将相关工作树归组以供检索，而分支和检出路径则描述相关性。移除的工作树不会授权其他检出目录写入其图谱；使用 git archive 重建受跟踪文件也无法恢复其未跟踪的 .kin/local 数据库。 kin cron 会为每个配置文件运行一次维护，并根据根目录路由会话摄取——cwd 位于某个配置文件根目录下的会话会进入该配置文件的图谱；默认配置文件接收其余未匹配的会话。如果没有 default_profile，最后会运行一次旧版剩余项处理，将未匹配的会话摄取到旧版图谱，并继续运行其维护（提醒、衰减、梦境）。kin cron --profile X 会固定运行单次处理并保持路由启用——它只会摄取归属 X 的会话；如果没有解析出配置文件，单独使用 --data-dir 会在指定目录中运行一次旧版全量处理。路由也适用于 kin ingest sessions|codex-sessions、MCP ingest 工具和 kin watch。显式指定的 --data-dir 若覆盖了配置文件的 data_dir，绝不会用活动配置文件标记尚未标记的数据库。

协作

多个 Agent 在同一图谱上协作时，可以通过包含成员、读取游标、共享资源、咨询锁和常驻注入消息的对话进行协调。

# Join a conversation as a member — members get unread tracking
kin coord join payments-refactor

# Attach a shared resource so members see who holds what
kin coord attach payments-refactor invoice-schema

# Advisory locks: signal "I'm working on this" — edits refuse foreign locks
kin lock invoice-schema --ttl 60 --note "migrating columns"
kin unlock invoice-schema

# Targeted message — only alice sees it as unread-for-her
kin coord post payments-refactor "schema branch is yours" --to alice@mbp

# Standing inject message — pushed into members' context until cleared or expired
kin coord inject payments-refactor set "Don't touch the invoice schema until migration lands"
kin coord inject payments-refactor clear

# Only the creator or a member may end it; --force acts as the operator
kin coord end payments-refactor --summary "migration landed"

常驻消息会随对话的 TTL 过期，且 TTL 不超过 7 天。成员只能清除自己的常驻消息；创建者可以清除任何常驻消息。

Agent 身份按以下顺序解析：KIN_AGENT_ID 环境变量 > 配置中的 agent_id > user@shorthost。kin whoami 会显示用户和解析出的 Agent ID。锁、认领、游标和消息定位都以此身份为准。

成员会在会话开始时的 prime 区块中看到自己的协作：

### Active collabs
- **payments-refactor** — 2 unread (focus: Extract billing service)
  COLLAB MSG: Don't touch the invoice schema until migration lands (from alice@mbp)
  Locked: invoice-schema (held by alice@mbp)
  Check the collab: coord_read payments-refactor

新的定向／广播消息和常驻注入也会通过提示词钩子在会话中途显示（并设有冷却时间，以免反复打扰）。显示方式可配置：

agent_id: jeremy-laptop        # optional; default user@shorthost
collab:
  enabled: true
  display: full                # full | minimal (one line per collab) | quiet (no prime block)
  prompt_cooldown_minutes: 10  # mid-session injection cooldown

锁仅供参考且会过期——过期的锁绝不会阻止任何人，cron 处理会清理过期的锁、对话和任务认领。

.kin/ 目录与继承

项目使用 .kin/ 目录来记录其沟通风格、工程标准和价值观。团队继承自组织，仓库继承自团队。知识图谱会延续这些特质。

~/.kindex/voices/acme.kin             # Org voice (downloadable, public)
    ^
    |  inherits
~/src/platform/.kin/config           # Platform team context
    ^
    |  inherits
~/src/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

.kin/ 目录是所有 kindex 项目制品的标准位置：

• .kin/config — 项目元数据（风格、领域、受众、继承关系）
• .kin/index.json — 用于 Git 跟踪的图谱快照
• .kin/code-map.json — 由 kin export code-map 生成的相对仓库路径代码映射
• .kin/.gitignore — 忽略 .kin/local、.kin/cache、.kin/tmp 和 .kin/private 下仅供本地使用的运行时状态 这些文件旨在随代码一同发布。不要在项目的 .gitignore 中忽略整个 .kin/ 目录；只忽略本地/私有子目录。 Kindex 按以下顺序解析项目配置：--project-path、KIN_PROJECT_PATH、 KIN_PROJECT、Git 工作树根目录，然后是当前目录。用户配置仍存放在 ~/.config/kindex/kin.yaml 中，并在项目配置下方进行深度合并，因此用户偏好保留在本地，而仓库的工作约定则随仓库一起传递。 存储位置按以下顺序选择：显式指定的 --project-path、KIN_PROJECT_PATH 或 KIN_PROJECT；然后是已存在的 .kin/local 存储；接着是配置的 data_dir；最后是 ~/.kindex。如果所选本地存储已纳入版本控制或是符号链接，系统会明确拒绝使用，而不会悄悄回退到其他存储。 生成的 .kin/ 快照采用规范化的 ID 键排序，并省略易变的时间戳，因此源内容未变时，重复导出不会导致 Git 差异不断变化。 并行分支可通过结构化合并驱动程序合并，无需手动解决冲突。该驱动程序会在首次运行 kin index 时自动注册（或在新克隆中运行 kin setup-merge 以（重新）安装）。随后，.kin/index.json 会按节点 ID 进行并集（以较新的 updated_at 为准），.kin/code-map.json 会按节点/边/层进行并集——这种方式可在不同机器间无损合并（从一台机器的本地 DB 重新生成会丢弃另一分支的节点），且输出与全新运行 kin index 的结果字节完全一致。Git 会调用 kin merge-kin 作为驱动程序；未注册该驱动程序的仓库会回退到 Git 的默认合并方式。切勿手动解决生成的 .kin 快照冲突。 纳入版本控制的 .kin 构件必须自包含且可跨机器使用：代码映射中的路径必须是相对于仓库的 POSIX 路径，任务/报告元数据不得指向 $HOME、/Users/...、/tmp/... 或其他开发者本地文件系统位置。如果后续工作需要扫描器报告作为证据，请随仓库提供本地子集或持久的共享构件，而不是本地路径引用。

kin export code-map 不同于常规图谱导出：它将当前代码结构投影为一个小型图谱，包含文件、类、函数、层和代码依赖，便于仪表板和 Agent 使用。当工具需要了解仓库的代码结构，而非完整的 Kindex 知识图谱时，请使用它。

导出	内容	用例
kin export	按受众范围筛选的 Kindex 节点、边、来源信息和图谱元数据	备份、交换或图谱级工具
kin export code-map	当前仓库的代码结构、代码依赖、层和相对仓库的文件路径	仪表板、代码导航和 Agent 工具

对于代码映射输出，src/file.py 可移植；/Users/alice/repo/src/file.py 和 C:\repo\src\file.py 则不可移植。

代码映射路径要求：

• 输出始终使用相对仓库的 POSIX 路径，即使源机器运行的是 Windows。
• 只有当绝对来源路径解析后位于指定的仓库根目录内时，才会对其进行规范化。
• 仓库根目录之外、格式错误或无法解析的路径会被省略，并附带安全警告，而不会泄露到构件中。
• 默认排除已归档节点，因为纳入版本控制的构件描述的是当前代码；API 调用方可通过 include_archived=True 选择包含这些节点，以进行历史分析。

支付服务会获得 Acme 的语气原则、平台的工程标准，以及自身的领域上下文。局部值会覆盖祖先值。列表合并时会去重。如果未显式设置 inherits，系统会自动遍历父目录。

旧式 .kin 文件（纯 YAML）会在首次访问时自动升级为 .kin/config。

请参阅 examples/kin-voices/ 获取可直接使用的语气模板。

架构

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):
      voyage-context-4 (contextual chunks) | openai | gemini | local

kin ask (answer.py), configured under `ask:`:
  classify   the question's kind, from its wording          (ask.plan: an LLM planner instead)
  retrieve   hybrid_search, one per named part, rank fusion (ask.top_k = 60)
  assemble   dated, oldest first, excerpted + directives    (ask.context_tokens = 5000,
                                                              ask.wide_context_tokens = 16000, ask.excerpt)
  answer     one call, the rules for that kind              (ask.effort = medium, ask.rules, ask.samples)

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 | claude -p | codex exec | opencode run
  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 | throttled Stop-time detach
  Dedup:         difflib.SequenceMatcher, 4-char title bucketing, 0.95 merge / 0.85 suggest
  Consolidation: suggestion auto-apply, bounded domain proposals, cluster summarisation
  Safety:        no tag-derived edges, overlap dedup, fcntl.flock, protected types

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

节点类型

知识：概念、文档、会话、人员、项目、决策、问题、构件、技能

代码智能

使用 kin ingest code --directory . 导入代码库结构：

• 模块节点（工件）——每个源文件对应一个，包含结构摘要：类、公开函数、签名、导入项

• 符号节点（概念）——每个类／接口／类型对应一个，包含方法签名

• 边——导入（depends_on）、继承（implements）、包含关系（context_of）、调用图（relates_to）

• 三级提取——ctags（100+ 种语言）、cscope（C/C++ 交叉引用）、tree-sitter（AST 调用图）

• 弹性回退——不受支持或未标记的文件仍会生成模块节点；可用的 tree-sitter 解析器仍可丰富这些模块，并在元数据中保留回退来源信息

• 增量处理——重新导入时通过文件哈希跳过未更改的文件

• Unity 项目（可选）——--unity（或 .kin/config 中的 code_ingest: {unity: true}）会索引序列化资源（.unity、.prefab、.asset、.mat、.controller、.anim），识别文本与二进制序列化格式，并附加每个资源的 .meta GUID，使模型能够解析基于 GUID 的引用；code_ingest.include_extensions 可映射更多扩展名（例如 .shader: Unity Shader）

• 项目排除项——.kin/config 中的 code_ingest.exclude 用于列出要排除的 fnmatch glob，此外还会排除内置项目（tests/*、vendor/*、node_modules/*、Unity 的 Library/* 等）。模式会匹配相对于 git 仓库根目录的每个文件路径，因此无论导入仓库根目录还是 client/，client/Assets/Licensed/* 都会指向相同文件；在仓库之外时，路径相对于导入目录。* 可以匹配 /，因此 *.mat 会匹配任意深度的文件。下次完整导入时，新增模式覆盖的文件节点会像已删除文件一样被清除，手动归档的内容则不受影响：

  code_ingest:
    unity: true
    exclude:
      - "client/Assets/Licensed/*"
      - "*.mat"
      - "*.prefab"
  

代码结构与决策、观察项和约束存储在同一张图中。搜索既能找到调用某个函数的内容，也能找到上次有人修改该函数时出问题的内容。

运维：约束（不变量）、指令（软规则）、检查点（飞行前检查）、观察项（注意标记）

CLI 参考（70+ 条命令）

核心

命令	描述
kin search <query>	混合 FTS5 + 图搜索，并使用 RRF 合并（--tags、--mine、--trusted-only）
kin context	为 AI 注入生成格式化上下文块（--level、--tokens、--trusted-only）
kin add <text>	快速记录，自动提取并建立链接（--tags、--type）
kin show <id>	显示包含边、来源信息和状态的完整节点详情
kin list	列出节点（--type、--status、--tags、--audience、--mine、--limit）
kin ask <question>	执行规划好的搜索，并根据带日期的证据生成答案（--as-of 用于设置今天的日期）；不使用 LLM 的搜索结果

知识管理

命令	描述
kin learn	从会话和收件箱中提取知识
kin link <a> <b>	在节点之间创建带权边
kin edit <id>	以符合策略的方式就地编辑（--title、--content、--append、--add-tags、--expires）
kin supersede <id> <text>	用新节点替换节点，同时保留历史记录（--reason）
kin alias <id> [add|remove|list]	管理节点的 AKA/同义词
kin register <id> <path>	将文件路径与节点关联
kin orphans	没有语义连接的语义节点（不包括会话）
kin trail <id>	时间历史和溯源链
kin decay	对过时节点/边应用权重衰减
kin recent	最近活跃的节点
kin tag [action]	会话标签：start、update、segment、pause、end、resume、list、show
kin archive [action]	搜索、恢复或运行可逆的慢图归档
kin candidate [action]	隔离捕获项审查：list、show、accept、reject、prune、erase
kin verify <node>	声明已验证，并可选指定 RFC 3339 有效时间间隔
kin invalidate <node>	记录声明的失效操作者、代码和排他结束时间
kin stale	重新哈希引用绑定节点；将过时节点从可信召回中降级（--rebind）
kin remind [action]	提醒：create、list、show、snooze、done、cancel、check、exec
kin mode [action]	对话模式：activate、list、show、create、export、import、seed

图分析

命令	描述
kin graph [mode]	仪表板：统计信息、中心性、社区、桥接点、路径起点
kin suggest	桥接机会建议（--accept、--reject）
kin skills [person]	某人的技能档案和专业知识
kin embed	为节点建立索引，以支持向量相似度搜索
kin embed plan/enqueue/reindex/drain/status	为完整或渐进式重新索引执行限定范围的嵌入维护

embedding.provider: voyage 默认使用 voyage-context-4。当配置的模型支持上下文分块嵌入时，Kindex 会存储稳定且相互重叠的分块向量，并将分块命中结果汇总回父节点。使用 kin embed plan --stale --kin ./path/.kin 估算定向更新， 使用 kin embed enqueue --stale --tags mea 通过 cron 逐步处理选定任务，或使用 kin embed reindex --target ./repo --limit 100 执行有界的前台处理。 除非不受支持的提供方/模型之后获得明确的上下文支持，否则会继续采用单向量策略。

嵌入队列排空过程会重试提供方的暂时性故障。对于确定性的输入大小拒绝，则会记录到本地隔离区（embed.quarantine.v1）， 因此 kin embed status 可以区分已排空的队列和不完整的向量覆盖情况，而不会悄然丢弃操作员诊断信息。

运维

命令	描述
kin status	图谱健康状况 + 运维摘要（--trigger、--owner、--mine）
kin set-audience <id> <scope>	设置隐私范围（private/team/org/public）
kin set-state <id> <key> <value>	设置指令/监视项上的可变状态
kin export	导出感知受众范围的图谱，并剥离 PII
kin mask scan	按键名统计已存储的已知机密值（--apply 会对其进行屏蔽）
kin export code-map	用于仪表板、代码导航和 Agent 工具的仓库相对代码映射
kin import <file>	从 JSON/JSONL 导入节点/边（--mode merge/replace）
kin sync-links	使用连接引用更新节点内容

协作与多 Agent

命令	描述
kin coord [action]	Agent 协调：start、post、read、list、end、join、attach、inject
kin lock <id>	获取节点的建议锁（--ttl、--note、--force）
kin unlock <id>	释放建议锁（对其他用户持有的锁使用 --force）
kin profile [action]	命名图谱配置：list、which、create

数据导入与外部来源

命令	描述
kin ingest <source>	从以下来源导入：projects、sessions、codex-sessions、files、commits、github、linear、code、all
kin cron	单次维护周期（用于 crontab/launchd）
kin dream	知识整合：去重并生成可审核的关联提案（--deep、--detach）
kin watch	监视新会话并导入（--interval）
kin analytics	会话分析与活动热图归档
kin index	写入 .kin/index.json 以便进行 git 跟踪
kin merge-kin	Git 合并驱动程序：对 .kin 构件执行结构化联合合并（由 git 调用）

基础设施

命令	描述
kin init	初始化数据目录
kin config [show|get|set]	查看或编辑配置
kin agent-config [show|set]	查看或调整各客户端/实例的 Agent 行为覆盖设置
kin policy [show|check]	显示或强制执行 .kin/config 中的项目工作策略
kin setup-merge	在当前 git 仓库中注册 .kin 结构化合并驱动程序
kin setup-hooks	将生命周期钩子安装到 Claude Code
kin setup-codex-hooks	将提示词时注意力钩子安装到 Codex
kin setup-codex-mcp	将 kindex MCP 服务安装到 Codex
kin setup-gemini-mcp	将 kindex MCP 服务安装到 Gemini CLI
kin setup-antigravity-mcp	将 kindex MCP 服务安装到 Google Antigravity
kin setup-antigravity-hooks	将生命周期钩子安装到 Google Antigravity
kin setup-opencode-mcp	将 kindex MCP 服务安装到 OpenCode
kin setup-cursor-mcp	将 kindex MCP 服务安装到 Cursor
kin setup-muse-mcp	将 kindex MCP 服务安装到 Muse
kin setup-cron	安装定期维护任务和专用提醒检查任务（launchd/crontab）
kin setup-claude-md	输出/安装推荐的 CLAUDE.md kindex 指令
kin setup-agents-md	输出/安装推荐的 AGENTS.md kindex 指令（Codex、OpenCode）
kin setup-gemini-md	输出/安装推荐的 GEMINI.md kindex 指令
kin setup-antigravity-md	输出/安装 Antigravity/GEMINI.md kindex 指令
kin setup-cursor-rules	输出/安装推荐的 kindex Cursor 规则（.mdc）
kin stop-guard	用于可执行提醒的停止钩子防护
kin doctor	健康检查并执行图谱约束（--fix；--fix-task-owners 会审计并修复当前项目存储中符合条件的过期 Claude 任务所有者）
kin migrate	将 Markdown 主题导入 SQLite
kin budget	大模型支出跟踪
kin attention	切换/检查/估算对话注意力提醒注入
kin attention-hook	用于提示词/工具事件的建议型注意力钩子
kin whoami	显示当前用户身份
kin changelog	查看变更内容（--since、--days、--actor）
kin log	查看近期活动日志
kin git-hook [install|uninstall]	管理仓库中的 git 钩子
kin prime	为 SessionStart 钩子生成上下文（--codebook）
kin compact-hook	压缩前的知识捕获

配置

配置采用类似 Git 的分层方式：全局默认值、全局配置，然后是本地配置。每一层都会与上一层进行深度合并，因此只需设置想要覆盖的选项。

层级	路径	用途
全局	~/.config/kindex/kin.yaml	用户级默认值
本地	项目根目录中的 .kin/config 或 kin.yaml	随代码提供的项目专属覆盖设置

使用 kin config set --global llm.enabled true 设置全局选项，或使用 kin config set llm.model claude-sonnet-4-6 设置项目本地选项。从仓库外部运行时，使用 --project-path /path/to/repo、KIN_PROJECT_PATH=/path/to/repo 或 KIN_PROJECT=/path/to/repo。

可通过以下三个层级调整面向 Agent 的行为：

# Global/project default for every client
kin config set attention.tick_interval 3

# Client default, e.g. every Claude session
kin agent-config set attention.tick_interval 2 --client claude

# One instance/conversation
kin agent-config set hooks.prime_tokens 1200 --client claude --scope instance --instance session-a

agent-config 只会写入获准的行为键，例如 attention.*、 sim.*、collab.prompt_cooldown_minutes 和 hooks.prime_tokens；它不能 更改存储路径或任意配置。Agent 应通过常规的工具／命令权限流程提出这些更改。 Antigravity 钩子会在运行 kin config set 或 kin agent-config set 前强制 弹出用户权限提示。

agents:
  clients:
    claude:
      attention:
        tick_interval: 2
        display: quiet
  instances:
    claude:session-a:
      client: claude
      attention:
        tick_interval: 1
      hooks:
        prime_tokens: 1200

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 (voyage-context-4 for Voyage)
  # api_key_env: ""                # empty = provider default (VOYAGE_API_KEY / OPENAI_API_KEY / GEMINI_API_KEY)
  # dimensions: 0                  # 0 = provider default (1024 / 1536 / 3072 / 384)
  # strategy: ""                   # empty/auto; contextual only when the model supports it
  # chunk_chars: 6000              # stable local chunks for contextual embedding models
  # chunk_overlap_chars: 600
  # max_group_chunks: 20
  # reindex_max_jobs: 200          # cron drain cap for queued embedding work
  # reindex_max_queue: 100000

budget:
  daily: 0.50
  weekly: 2.00
  monthly: 5.00

capture:
  candidate_ttl_days: 7          # positive TTL for quarantined automatic captures

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:
  - ~/src
  - ~/notes

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
  auto_snooze_max: 86400         # repeated auto-snoozes double up to this cap
  max_action_overdue: 86400      # stale actions notify only; 0 disables guard
  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: true    # launch throttled detached dream from Claude Stop hook
  dream_min_interval: 3600       # seconds between scheduled/hook dream starts
  dream_max_domain_link_suggestions: 50 # pending domain-review cap per graph
  channels:
    slack:
      enabled: false
      webhook_url: ""
    email:
      enabled: false
      smtp_host: ""
      to_addr: ""

自动延后会在不延长操作时效窗口的情况下重试通知。使用 kin remind snooze 主动延后会将该窗口推迟到延后时间结束；kin remind exec 会主动运行某项操作。 没有来源信息的旧延后记录会保留原有的推迟语义，因为过去自动延后和手动延后 的存储方式相同。此更改不会对现有提醒积压进行分类或修复。

使用 kin attention estimate --messages 1000 可估算固定提示词窗口的成本。当客户端提供稳定的会话 ID 时，会保留对话用量记录。由钩子驱动的注意力机制不会退回使用 cwd 充当虚假的对话 ID，因为这会导致同一仓库中打开的两个聊天相互污染。

遮蔽已知密钥

让 Kindex 知道存放密钥的环境文件位置，例如 ~/.profile，它便会在存储或显示文本前将其中的值替换为键名：sk-... 会变成 $OPENAI_API_KEY。这适用于所有写入操作（添加、学习、编辑、取代、摄取、MCP 工具、钩子，因此 FTS 和嵌入从不会接触这些值）和所有输出（prime、上下文、搜索、显示、MCP 响应），因此在启用该功能前写入的行也会被遮蔽。

# ~/.config/kindex/kin.yaml only; a project's .kin/config cannot set or weaken it
secret_mask:
  files: [~/.profile]
  # keys: [OPENAI_API_KEY, github, "AWS_*_KEY"]  # optional, see below
  # min_length: 8

Kindex 会读取 [export ]NAME=VALUE 格式的行，去除匹配的引号和未加引号值末尾的 #comment，并跳过包含 $ 或反引号的值，以及短于 min_length 的值。keys 条目会匹配名称中包含该条目的任何名称，且不区分大小写；* 会匹配任意长度的字符，因此完整名称会匹配自身。未设置 keys 时，会选中名称中包含 KEY、TOKEN、SECRET、PASSWORD、PASSWD、PASS、PW、CREDENTIAL、AUTH、PRIVATE、SID、DSN、WEBHOOK、COOKIE、CLIENT_ID、ACCOUNT_ID 或 API 的名称。较长的值会优先替换；多个名称共享同一值时，以文件中最先出现的名称为准。文件更改时会重新读取；文件缺失或无法读取时，不会遮蔽任何内容，并会记录一条警告。

已存储的行会保留原始字节，直到你清理它们：

kin mask scan          # occurrences per key name and table.column, never values
kin mask scan --apply  # snapshot, rewrite as $NAME, rebuild FTS, requeue embeddings

--apply 也会清理节点归档。它会像自动合并一样，先为每个数据库创建快照；快照仍包含旧值，因此检查结果后请将其删除。标识符（主键和外键）会被报告，但不会重写。

开发

make dev          # install with dev + LLM dependencies
make test         # run the full test suite
make check        # lint + test combined
make clean        # remove build artifacts

许可证

MIT。版权所有 (c) 2026 Wander。Kindex 是 Wander 项目。

Kinbase 兼容性

使用 kin kinbase sync --repo PATH 读取已签名的 Kinbase 事实和未解决的问题。 Kindex 会保留经来源限制的现有状态，区分原始证据与精简快照，且绝不写入 Kinbase 事件。请参阅读取器指南。