你的 AI 代理总是犯同样的错误。它在会话之间会忘记你的偏好。它无法从重复中学习。

instinct 解决了这个问题。它观察你代理会话中的模式，跟踪随时间变化的置信度，并将重复出现的模式自动提升为代理会遵循的建议，无需你反复叮嘱。

适用于任何兼容 MCP 的代理：Claude Code、Cursor、Windsurf、Goose、Codex 等。

工作原理

         observe           track            promote           suggest
        ┌───────┐       ┌───────┐        ┌───────┐        ┌───────┐
  You   │Record │  +1   │ Count │  >=5   │Mature │  >=10  │ Rule  │
  work  │pattern├──────>│ hits  ├───────>│suggest├───────>│ auto- │
        └───────┘       └───────┘        └───────┘        │ apply │
                                                          └───────┘

观察 — 在代理工作时记录模式（工具序列、偏好、重复修复）
跟踪 — 每次重新观察都会增加置信度
提升 — 置信度 >= 5 变为 mature（建议），>= 10 变为 rule（自动应用）
建议 — 成熟的模式无需明确指令即可引导代理行为

功能特性

自动提升 — 基于置信度阈值，模式会自动通过成熟度级别（原始 → 成熟 → 规则 → 通用）进行提升
自动链检测 — 根据观察时间戳自动发现顺序模式（seq:A->B），无需手动定义序列 (v1.4.0)
有效性评分 — 跟踪建议的模式是否被后续观察所确认，计算确认率 (v1.4.0)
置信度历史 — 每个模式置信度随时间演变的完整时间线
跨项目学习 — 在 2 个以上项目中观察到的规则会自动提升为 universal（通用）级别
多平台导出 — 将规则导出为 CLAUDE.md、.cursorrules、.windsurfrules 或 Codex 格式
代理技能导出 — 将规则导出为与 agentskills.io 兼容的 SKILL.md
CLAUDE.md 注入 — 向 CLAUDE.md 文件注入/导入规则（幂等）
近重复检测 — 查找相似模式并通过别名合并它们
模式别名 — 将不同拼写的观察结果重定向到规范模式
全文搜索 — 基于 FTS5 的模式、元数据和解释全文搜索
垃圾回收 — 衰减陈旧模式、合并重复项、清理孤立项、重建索引
备份与恢复 — 带有健康检查的 SQLite 级备份和恢复

安装

pip install instinct-mcp

60秒快速入门

如果尚未安装，请运行 pip install instinct-mcp。
将 instinct 添加到你的 MCP 客户端。
Claude Code（一行命令）：
```
claude mcp add instinct -- instinct serve
```
Cursor / Windsurf / Goose / 其他 MCP 客户端 — 添加到你的客户端 MCP 配置中：
```
{
  "mcpServers": {
    "instinct": {
      "command": "instinct",
      "args": ["serve"]
    }
  }
}
```
记录一个模式并请求建议：

instinct observe "seq:test->fix->test"
instinct suggest

如果 suggest 返回空列表，请继续观察重复出现的模式。当置信度达到 mature 级别时，建议就会出现。

快速验证

instinct observe "seq:test->fix->test"
instinct suggest

仓库健康状况

CI 和 CodeQL 在推送和拉取请求时运行
Dependabot 跟踪每周更新（GitHub Actions + pip）
受保护的默认分支（master）需要审查并解决对话

快速开始

1. 添加到你的代理

Claude Code — 添加到项目根目录的 .mcp.json 中：

{
  "mcpServers": {
    "instinct": {
      "command": "instinct",
      "args": ["serve"]
    }
  }
}

Codex CLI — 添加到 ~/.codex/config.toml 中：

[mcp_servers.instinct]
command = "instinct"
args = ["serve"]

Cursor / Windsurf — 添加到你的 MCP 配置中：

{
  "mcpServers": {
    "instinct": {
      "command": "instinct",
      "args": ["serve", "--transport", "sse"]
    }
  }
}

2. 观察它学习

当你工作时，你的代理开始注意到模式：

Session 1:  observe("seq:test->fix->test")          → confidence 1 (raw)
Session 3:  observe("seq:test->fix->test")          → confidence 3 (raw)
Session 5:  observe("seq:test->fix->test")          → confidence 5 (mature ✓)
            suggest() → "When tests fail, apply fix and re-run tests"

经过足够的重复，instinct 开始将模式反馈给你——你的代理会适应你的工作方式。

模式长什么样

# Tool sequences your agent repeats
instinct observe "seq:lint->fix->lint"
instinct observe "seq:build->test->deploy"

# Your preferences it should remember
instinct observe "pref:style=black" --cat preference
instinct observe "pref:commits=conventional" --cat preference

# Fixes it keeps rediscovering
instinct observe "fix:missing-import" --cat fix_pattern
instinct observe "fix:utf8-encoding-windows" --cat fix_pattern

# Tools that work better together
instinct observe "combo:pytest+coverage" --cat combo

命名约定

前缀	用途	示例
`seq:`	动作序列	`seq:lint->fix->lint`
`pref:`	用户偏好	`pref:style=black`
`fix:`	重复修复	`fix:missing-import`
`combo:`	工具组合	`combo:pytest+coverage`

成熟度级别

级别	置信度	行为
raw	< 5	已观察、已存储，尚不可操作
mature	>= 5	由 `suggest()` 返回 — 代理将其用作指导
rule	>= 10	由 `export_rules()` 导出 — 足够强大以自动应用
universal	规则 + 2 个项目	跨项目规则，在任何地方都会被建议

MCP 工具

工具	功能
`observe`	记录模式（重复时自动增加置信度）
`suggest`	获取成熟模式以指导当前行为
`list_instincts`	浏览所有已观察到的模式（带过滤）
`get_instinct`	查找特定模式
`consolidate`	提升跨越置信度阈值的模式 + 检测链
`search_instincts`	跨模式和元数据的全文搜索
`stats`	instinct 存储的统计摘要
`export_rules`	将规则级模式导出为结构化数据
`alias_pattern`	创建别名以合并重复模式
`import_patterns`	从字典列表批量导入模式
`session_summary`	会话结束快照（带自动合并）
`trending`	显示近期增长最快的模式
`export_claude_md`	导出格式化为 CLAUDE.md 的规则
`export_skill`	将规则导出为代理技能 (SKILL.md / agentskills.io)
`inject_claude_md`	将规则注入 CLAUDE.md 文件（幂等）
`find_duplicates`	查找近重复模式以进行合并
`import_claude_md`	从 CLAUDE.md 文件导入模式
`history`	模式随时间的置信度历史
`export_platform`	为 Cursor、Windsurf、Codex 等导出规则
`gc`	垃圾回收：衰减 + 去重 + 孤立项清理 + FTS 重建
`detect_chains`	根据时间戳自动检测顺序模式链
`effectiveness`	显示建议有效性评分（确认率）

MCP 提示词

提示词	功能
`instinct_rules`	获取所有 instinct 规则作为代理指令
`instinct_suggestions`	获取当前项目的成熟模式建议

CLI 参考

# Core
instinct observe <pattern>       # Record/reinforce a pattern
instinct get <pattern>           # Look up a specific pattern
instinct list                    # List all instincts
instinct suggest                 # Get mature suggestions
instinct consolidate             # Auto-promote + detect chains
instinct stats                   # Summary statistics
instinct delete <pattern>        # Remove a pattern

# Analysis
instinct trending                # Fastest-growing patterns
instinct history <pattern>       # Confidence history over time
instinct effectiveness           # Suggestion confirmation rates
instinct detect-chains           # Auto-detect sequential chains

# Export
instinct export-rules            # Export rules as JSON
instinct export-claude-md        # Export rules as CLAUDE.md markdown
instinct export-skill            # Export rules as Agent Skill (SKILL.md)
instinct export-platform <fmt>   # Export for cursor/windsurf/codex
instinct export-all              # Export all instincts as JSON

# Import & Sync
instinct inject <path>           # Inject rules into CLAUDE.md (idempotent)
instinct import-claude-md <path> # Import patterns from CLAUDE.md
instinct import <file.json>      # Bulk import from JSON

# Maintenance
instinct gc                      # Garbage collection (decay + dedup + cleanup)
instinct decay                   # Reduce stale patterns
instinct dedup                   # Find/merge near-duplicate patterns
instinct alias <pat> <target>    # Create a pattern alias
instinct aliases                 # List all aliases

# Infrastructure
instinct serve                   # Start MCP server
instinct fingerprint             # Print project fingerprint for cwd
instinct backup                  # Create database backup
instinct restore <file>          # Restore from backup
instinct doctor                  # Run health checks

所有命令均支持 --json 以获取结构化输出。

观察选项

instinct observe "seq:a->b" \
  --cat sequence              # Category: sequence|preference|fix_pattern|combo
  --source claude-code        # Which agent/tool recorded this
  --project auto              # Project fingerprint (auto-detected from cwd)
  --explain "why this matters"

服务器选项

instinct serve                              # stdio (default, for Claude Code)
instinct serve --transport sse              # SSE for remote/HTTP clients
instinct serve --transport streamable-http  # Streamable HTTP
instinct serve --port 3777                  # Custom port (default: 3777)

Python 库

from instinct.store import InstinctStore

store = InstinctStore()  # uses ~/.instinct/instinct.db

# Record patterns
store.observe("seq:test->fix->test", source="my-tool")
store.observe("seq:test->fix->test")  # confidence = 2

# Query
suggestions = store.suggest()                     # mature+ patterns
results     = store.search("test")                # full-text search
rules       = store.export_rules()                # rule-level only

# Lifecycle
store.consolidate()                               # promote + detect chains
store.decay(days_inactive=90)                     # fade stale patterns

# Auto-chain detection
chains = store.detect_chains(window_minutes=5, min_occurrences=3)

# Effectiveness scoring
eff = store.effectiveness(days=30)

# Stats
print(store.stats())
# {'total': 42, 'raw': 30, 'mature': 10, 'rules': 2, 'avg_confidence': 4.2, ...}

自定义数据库路径

store = InstinctStore(db_path="/path/to/custom.db")

跨项目学习

instinct 会将你的工作目录哈希为项目指纹。这意味着：

项目特定模式仅在你处于该项目时才会建议
全局模式（空项目字段）在任何地方都会建议
通用规则 — 在 2 个以上项目中达到 rule 级别的模式会自动提升为 universal，并在所有项目中建议

# See your current project's fingerprint
instinct fingerprint
# → a1b2c3d4e5f6

存储

数据库： SQLite (WAL 模式) 位于 ~/.instinct/instinct.db
依赖： 仅 mcp>=1.0.0
Python： >= 3.11
配置： 可选 ~/.instinct/config.toml 用于覆盖阈值

对比分析

	instinct	手动 CLAUDE.md	.cursorrules
自动学习	是	否	否
跨会话记忆	是	是	是
置信度评分	是	否	否
自动链检测	是	否	否
有效性跟踪	是	否	否
陈旧模式衰减	是	否	否
跨项目学习	是	否	否
跨代理工作	是 (MCP)	仅 Claude	仅 Cursor
多平台导出	是	N/A	N/A
需要手动编辑	否	是	是

许可证

MIT

instinct

目录