instinct：一个基于置信度的 AI Agent 自学习记忆系统

Claude Code、Cursor、GitHub Copilot 这类 AI 编码 Agent 在单次会话中表现出色，但每次新会话都从零开始。没有连续性，也没有"上次遇到过类似情况"的判断力。

现有的应对方式是CLAUDE.md 文件、系统提示词、手动编写的规则列表，这些本质上都是把人当作记忆载体。人去观察模式、记录下来、维护文件，Agent 只负责执行。

其实记忆应当是 Agent 在反复实践中习得的，而非人工分配的。

核心思想：基于置信度的学习

多数 AI Agent 记忆系统采用显式建模，即人写规则、Agent 遵照执行。instinct 走了一条不同的路，借鉴了大脑中习惯形成的机制：

观察 重复 成熟 建议

Agent 首次执行某个操作时，instinct 将其记录为一条 raw 观察，初始置信度为 1。同一模式再次出现，置信度递增。当置信度突破第一个阈值，模式进入 mature 状态，就出现在建议列表中；如果获得了更高的阈值，模式晋升为 rule，可以自动应用。

Confidence 1-4:   raw      (observed, not actionable)

Confidence 5-9:   mature   (ready to suggest)

Confidence 10+:   rule     (strong enough to auto-apply)

什么时候一个模式算"准备好了"？没有人来做判断，数据说了算。

工作原理

1、观察

每当发现一个反复出现的模式——一组工具调用序列、某种编码偏好、一类频繁出现的修复——就将其记录下来：

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

instinct observe "pref:style=black" --cat preference

instinct observe "fix:missing-import" --cat fix_pattern

命名约定通过前缀区分模式类别：

seq:   Action sequence     (e.g. seq:lint->fix->lint)

pref:   User preference     (e.g. pref:stdlib-first)

fix:   Recurring fix       (e.g. fix:missing-import)

combo: Tools used together (e.g. combo:pytest+coverage)

每次观察都是一个 upsert 操作：模式已存在则置信度加 1，不存在则以置信度 1 新建。

2、合并

会话结束时（或定期），运行 consolidate 触发自动晋升：

instinct consolidate

# Promoted to mature: 3

# Promoted to rule: 1

# Total instincts: 12

学习在这一步完成。累积观察次数达标的模式自动晋升，不需要人介入。

3、建议

下一次会话开启时，Agent 向系统请求建议：

instinct suggest

#   seq:test->fix->test    conf=8  [mature]  sequence

#   pref:stdlib-first      conf=12 [rule]    preference

# 2 suggestions

只有 mature 和 rule 级别的模式会返回。Raw 观察始终保持静默，直到置信度积累到位。

架构

这三个组件不需要外部依赖（MCP SDK 除外），而且SQLite 也内置于 Python 标准库；MCP 服务器基于 FastMCP 实现。

为什么选择 SQLite？

备选方案评估过 JSON 文件、Redis、简单的键值存储。而SQLite原因有四：可用 SQL 按置信度、类别、项目任意查询；ACID 事务保证状态一致性；无需守护进程、无需额外配置，整个存储就是一个文件；迁移学习历史只需复制这个文件。

核心的 upsert 查询把创建和更新合并到了一条语句里：

INSERT INTO instincts (pattern, category, confidence, ...)

VALUES (?, ?, 1, ...)

ON CONFLICT(pattern) DO UPDATE SET

  confidence = confidence + 1,

  last_seen = excluded.last_seen

首次观察建行，重复观察加分。一条查询就搞定了

为什么选择 MCP？

Model Context Protocol 是一个将 AI Agent 与外部工具连接的开放标准。instinct 实现为 MCP 服务器后，天然兼容所有支持该协议的 Agent——Claude Code、Cursor、Goose，或任何其他 MCP 客户端。

{

"mcpServers": {

  "instinct": {

    "command": "instinct",

    "args": ["serve"]

  }

}

}

配置文件里加上这几行，任意 MCP Agent 即可接入自学习记忆。

项目感知的学习

并非所有模式都具有普适性。"用 black 格式化"也许适用于某个项目，换一个项目就不适用了。所以instinct 用项目指纹来划定作用域：

def project_fingerprint(path=None):

  p = Path(path or Path.cwd()).resolve()

  return hashlib.sha256(str(p).encode()).hexdigest()[:12]

每个项目依据其目录路径生成一个稳定的 12 字符 SHA256 指纹。模式分为两类：项目级模式仅在对应项目中生效；全局模式（project 字段为空）在所有项目中可见。

Agent 调用suggest时，返回结果同时包含全局模式和当前项目的专属模式。Python 项目的格式化偏好不会渗透到 Go 项目中。

衰减：遗忘过时的模式

人的习惯长期不用会逐渐淡化，instinct 中的模式也遵循同样的逻辑。

instinct decay --days 90

超过 90 天未被观察到的模式，置信度减 1。减到零的模式自动删除。系统以此避免积累过时的建议，保持记忆库的时效性。

实际使用

以下是与 Claude Code 集成的典型场景。在 MCP 服务器的指令中，instinct 对 Agent 说：

Use 'observe' to record patterns you notice. Use 'suggest' to get mature patterns that should guide your behavior. Run 'consolidate' periodically to auto-promote high-confidence patterns.

几次会话之后，Agent 开始形成自己的操作手册：

seq:test->fix->test          conf=8   [mature]   — Always re-run tests after fixes

pref:stdlib-first            conf=12  [rule]     — Prefer stdlib over third-party

fix:missing-init             conf=6   [mature]   — Check for __init__.py in new packages

combo:pytest+coverage        conf=5   [mature]   — Always run coverage with tests

没有人显式地教过 Agent 这些内容——它从跨会话的重复行为中自行归纳出来。到第五次会话，Agent 对工作流的熟悉程度已经超过一个新加入的团队成员。

深入底层：数据库 Schema

完整的 SQLite schema 如下：

CREATE TABLE instincts (

  pattern    TEXT PRIMARY KEY,

  category   TEXT NOT NULL DEFAULT 'sequence',

  confidence INTEGER NOT NULL DEFAULT 1,

  first_seen TEXT NOT NULL,

  last_seen  TEXT NOT NULL,

  source     TEXT NOT NULL DEFAULT '',

  project    TEXT NOT NULL DEFAULT '',

  promoted   INTEGER NOT NULL DEFAULT 0,

  metadata   TEXT NOT NULL DEFAULT '{}'

)

一张表，构成完整的数据模型。promoted字段对应成熟度等级：0 = raw，1 = mature，2 = rule。metadata列存储任意 JSON，用于在不做 schema 迁移的前提下扩展功能。

Python API

CLI 和 MCP 服务器之外，instinct 也提供了 Python API：

借助该 API，instinct 可以方便地嵌入自定义工具链、CI 流水线或数据分析面板。

本地测试

pip install instinct-mcp

# 记录你的第一个模式

instinct observe "seq:your->first->pattern"

# 查看系统学到了什么

instinct suggest

# 启动 MCP 服务器用于 Agent 集成

instinct serve

代码完全开源，包已发布在 PyPI 上。

https://github.com/yakuphanycl/instinct

by Yakuphan Yucel

点个在看你最好看！