Innate — 自成长 Agent 程序性知识层

一句话定位: 一个可嵌入可外挂、自成长、引擎可换的 agent 程序性知识层系统。
它不做编排(对 LangGraph / Claude Code / 裸 API 中立), 只解一件事——在有限 context 预算内, 组装最相关、最精确的知识, 并让这套知识随使用自我进化。

Innate 管理的不是「世界是什么样 / 用户偏好是什么」那种陈述性记忆, 也不是一次写定再也不变的静态技能仓库。它管理的是程序性知识(Procedural Knowledge)——「事情该怎么做, 哪种方式在这个上下文里更有效」。每一块知识从进库起都在被真实使用结果考核: 好用的升权, 失效的降权归档, 灵感可孵化晋升, 整库越用越准。

核心闭环

五个核心闭环必须完整, 缺一就不算"知识层":

召回: query → recall → context(双向量余弦相似度 + 标量过滤, 同步纯数学)
观测: context → use → trace(记录哪些块被用了、结果如何)
成长: trace → distill → pending(离线蒸馏新经验)
治理: usage → confidence → curate(EMA 置信度更新 + Curate 归档)
安全: pending/archived/不物理删(默认 sanitize 钩子, 黑名单 + red action)

默认同步召回路径绝不调用任何 LLM/小模型——Innate 是图书管理员, 不是阅读者兼编辑。只有调用方显式开启可选 Refiner 时才执行 trim/adapt。

安装

Rust 核心 (唯一运行时)

# 从源码编译
cd core && cargo build --release
cp target/release/innate ~/.local/bin/   # 加入 PATH

# 验证
innate inspect

Python SDK

pip install innate-py   # 或 pip install -e sdks/python/

TypeScript SDK

npm install @innate/sdk  # 或 npm install ./sdks/typescript/

MCP 服务 (Claude Code / Claude Desktop)

在 .claude/settings.json 中添加:

{
  "mcpServers": {
    "innate": {
      "command": "innate",
      "args": ["mcp"]
    }
  }
}

配置后 Agent 可直接使用 innate_recall、innate_record 等 MCP 工具, 无需手动调用 CLI。

Daemon (Linux only)

后台守护进程，监听指定目录下的日志文件和 JSON Hook 事件，自动桥接到知识层：

# 启动: 监听一个或多个目录
innate daemon start --watch /path/to/log/dir

# 查看运行状态和错误统计
innate daemon status

# 停止
innate daemon stop

Daemon 通过 subprocess 调用 innate CLI，不直接打开知识库；其自身状态（文件偏移、已处理事件、会话 trace）记录在独立的 daemon_state.sqlite 中。

接入 Agent (MCP 配置)

推荐方式: MCP 服务 — Agent 通过 MCP 工具直接操作知识库, 无需 CLI 权限。

步骤

编译并安装 Rust 二进制:

cd core && cargo build --release
cp target/release/innate ~/.local/bin/

在 .claude/settings.json 添加 MCP 配置:

{
  "mcpServers": {
    "innate": {
      "command": "innate",
      "args": ["mcp"],
      "env": {
        "INNATE_DB": "/path/to/your/personal.db"
      }
    }
  }
}

验证初始化:

innate inspect   # 应输出空库健康报告

Agent 工作规范

配置完成后, 将以下工作规范发送给 Agent:

知识层使用规范

操作类别 MCP 工具

Agent 可直接执行 innate_recall · innate_record · innate_evolve · innate_inspect

确认后执行 innate_add · innate_spark

仅人工治理 innate_approve · innate_archive · innate_invalidate · innate_restore · innate_mature_spark · innate_promote_spark · innate_drop_spark

工作流程

每次任务开始前调用 innate_recall(query="<任务意图>"), 将结果纳入计划

任务结束后调用 innate_record(trace_id=..., outcome="ok"|"fail"), 闭合 trace

发现值得保留的经验或灵感时, 先提炼并向用户确认; 得到同意后调用 innate_add 或 innate_spark

判断知识已失效时, 只提出治理建议, 不直接执行治理动作

会话结束时调用 innate_evolve(trigger="manual") 触发蒸馏

操作类别	MCP 工具
Agent 可直接执行	`innate_recall` · `innate_record` · `innate_evolve` · `innate_inspect`
确认后执行	`innate_add` · `innate_spark`
仅人工治理	`innate_approve` · `innate_archive` · `innate_invalidate` · `innate_restore` · `innate_mature_spark` · `innate_promote_spark` · `innate_drop_spark`

快速开始

# 1. 写入知识
innate add "Python 列表推导式比 map/filter 更易读" --kind note --trigger "python 列表处理"

# 2. 召回知识 (返回 top 块, 含 trace_id)
innate recall "python 列表优化" --budget 2000 --format json

# 3. 补全 trace (闭合经验链路)
innate record <trace_id> --outcome ok --used <chunk_id1>,<chunk_id2>

# 4. 触发成长 (蒸馏 + 治理)
innate evolve --trigger manual

# 5. 体检 (健康信号 + 建议命令)
innate inspect

Python SDK

from innate import KnowledgeBase

kb = KnowledgeBase("personal.db")  # 或通过 INNATE_DB 环境变量指定

# 1. 写入
note_id = kb.add("经验内容", kind="note", trigger_desc="触发场景")
spark_id = kb.spark("一个待探索的灵感", trigger_desc="相关场景")

# 2. 召回 (同步纯数学)
ctx = kb.recall(
    "任务描述",
    budget=6000,
    include_sparks=True,
)
for chunk in ctx.knowledge:
    print(chunk["id"], chunk["content"])

# 3. 记录使用
kb.record(
    ctx.trace_id,
    outcome="ok",
    used=[note_id],
    output_summary="解决了 X",
)

# 4. 成长
result = kb.evolve(trigger="manual")

# 5. 治理 (人工操作)
kb.approve(pending_id)
kb.archive(note_id, reason="stale")
kb.invalidate(note_id, reason="逻辑错误")
kb.restore(archived_id)

# 6. 灵感生命周期
kb.mature_spark(spark_id, to="sprouting")
kb.mature_spark(spark_id, to="incubating")
new_id = kb.promote_spark(spark_id, to="note")
kb.drop_spark(spark_id, reason="已证伪")

# 7. 体检
report = kb.inspect()

TypeScript SDK

import { KnowledgeBase, McpClient } from "@innate/sdk";

// CLI subprocess 模式 (同步, 适合脚本)
const kb = new KnowledgeBase({ dbPath: "personal.db" });

const ctx = kb.recall("任务描述", { budget: 6000 });
kb.record(ctx.trace_id, { outcome: "ok", used: [chunkId] });
kb.add("经验内容", { kind: "note", triggerDesc: "触发场景" });
kb.evolve("manual");
const report = kb.inspect();

// MCP 客户端模式 (异步, 适合 Agent 集成)
const client = new McpClient({ dbPath: "personal.db" });
await client.initialize();

const result = await client.recall("任务描述", { budget: 6000 });
await client.record(result.trace_id, { outcome: "ok" });
await client.add("新知识", { kind: "note" });
await client.inspect();

client.close();

CLI 子命令一览

CLI 是 SDK Public API 的薄封装, 不新增任何知识层逻辑——只做参数解析和格式化输出。

子命令	能力域	说明
`innate recall <query>`	读	`--budget` · `--top` · `--include-sparks` · `--format text\|json`
`innate record <trace_id>`	写	`--outcome ok\|fail\|unknown` · `--used` · `--output-summary` · `--nomination` · `--source`
`innate evolve`	成长	`--trigger manual\|scheduled\|threshold`
`innate inspect`	调试	库体检: 5 个健康信号 + 当前参数
`innate add <content>`	写入	`--kind note\|skill` · `--trigger` · `--anti-trigger` · `--skill-name` · `--source`
`innate spark <content>`	灵感	`--trigger`
`innate mature-spark <id> <to>`	治理	to: `sprouting\|incubating` (只允许前向)
`innate promote-spark <id>`	治理	`--to note\|skill`
`innate drop-spark <id>`	治理	`--reason`
`innate approve <id>`	治理	pending → active
`innate archive <id>`	治理	`--reason`
`innate invalidate <id>`	治理	`--reason` (归档 + 黑名单)
`innate restore <id>`	治理	archived → active; 若此前 invalidate, 同步撤销 hash 黑名单
`innate mcp`	集成	启动 MCP stdio 服务 (JSON-RPC 2.0), 供 Claude Code / Desktop 使用
`innate daemon start`	集成	后台日志/Hook 监听守护进程 `--watch <dir>` (Linux only)
`innate daemon status`	集成	查看 daemon 运行状态与错误统计
`innate daemon stop`	集成	停止运行中的 daemon

`recall` 输出格式

text — 人类可读, 不含 trace 信息
json — 机器可读, 含 trace_id / knowledge / sparks / empty 字段

`inspect` 输出

库体检 (无参) — 5 个健康信号:

知识债务比 (含僵尸块, < 0.3 正常)
embed 重建队列 (待补向量的 chunk 数)
灵感提示 (反复浮现的 spark id)
stale screening (卡死的 distill 日志)
本周期蒸馏成本 (token 估算)

末尾打印当前 recall_params / curate_params 便于调参。

MCP 工具 (`innate mcp` 暴露的 13 个工具)

MCP 工具	对应能力
`innate_recall`	召回知识
`innate_record`	记录 trace
`innate_add`	写入知识块
`innate_spark`	创建灵感
`innate_evolve`	触发成长
`innate_inspect`	库体检
`innate_approve` / `innate_archive` / `innate_invalidate` / `innate_restore`	治理
`innate_mature_spark` / `innate_promote_spark` / `innate_drop_spark`	灵感生命周期

系统架构

四种接入模块，共用一套 Rust KnowledgeBase Core：

MCP    (innate mcp)           ──────────────────────────┐
CLI    (innate <cmd>)          ──────────────────────────┤──> KnowledgeBase Core ──> SQLite
SDKs   (Python / TypeScript)   ──> CLI ─────────────────┤
Daemon (innate daemon start)   ──> CLI ─────────────────┘

模块	实现方式	说明
MCP	直接调用 Core lib	JSON-RPC 2.0 over stdio；13 个工具；供 Claude Code / Claude Desktop 使用
CLI	直接调用 Core lib	clap 薄封装；完整 Public API 的命令行入口
Python SDK	subprocess 调用 CLI	`innate-py`，零额外依赖
TypeScript SDK	subprocess 调用 CLI + async MCP client	`@innate/sdk`，Node.js 18+
Daemon	subprocess 调用 CLI	后台监听日志 / JSON Hook；自动触发 recall / record / evolve；事件幂等、会话 trace、错误统计、断点续读（Linux only）

Innate System
├── Rust 核心 (core/)
│   ├── KnowledgeBase (lib)      8 类 Public API, SQLite + 纯 Rust 余弦相似度
│   ├── CLI (innate <cmd>)       clap 薄封装, 参数解析 → KnowledgeBase 调用
│   ├── MCP Server (innate mcp)  JSON-RPC 2.0 over stdio, 13 个 MCP 工具
│   └── Daemon (innate daemon)   后台日志/Hook 监听, subprocess → CLI (Linux only)
│
├── 向量搜索                     f32 BLOB 存储 + 全扫描余弦相似度 (零 native 扩展)
│   ├── vec_content              内容向量 (BLOB)
│   └── vec_trigger              触发向量 (BLOB)
│
├── SDKs
│   ├── sdks/python/             innate-py  — subprocess → CLI, 零额外依赖
│   └── sdks/typescript/         @innate/sdk — CLI subprocess + async MCP client
│
└── skills/innate-memory/        SKILL.md (MCP 工具为主, CLI 为 fallback)

核心特性

双向量召回: content_vec + trigger_vec, 按 w_content / w_trigger / w_confidence 融合排序
置信度驱动: EMA 更新 + 时效加权 (显式信号) + 时间衰减, 知识越用越准
零 native 扩展: 向量存为 f32 BLOB, Rust 原生余弦相似度, 无 sqlite-vec / C 扩展依赖
MCP 原生集成: innate mcp 暴露 13 个工具, Claude Code / Claude Desktop 开箱可用
hard dep fail-closed: 召回时若 hard 依赖不可用/被归档, 直接丢弃整个 seed, 绝不返回半截闭包
零主动行为: SDK 永不自发行动, 所有成长由外部触发 (evolve trigger: manual / scheduled / threshold)
sanitize 三态合同: 钩子返回 (cleaned, action), action ∈ {allow, redact, discard}; discard 拒绝写入, redact 落点 confidence 上限 0.4
spark 独立生命周期: maturity = seed → sprouting → incubating, 仅 promote / drop 时离场; 不参与 confidence 排序, 不被低分归档
原子双向量写入: chunk + content_vec + trigger_vec 同 BEGIN IMMEDIATE 事务写入, 任一失败回滚
schema 自动迁移: 启动时自动 apply 增量迁移, 库空直接 exec schema.sql

兼容性

核心运行时: Rust 1.70+ (bundled SQLite, 零外部运行时依赖)
Python SDK: Python 3.8+ (subprocess, 零额外依赖)
TypeScript SDK: Node.js 18+ (child_process, 零额外依赖)
Daemon: Linux only (依赖 /proc 与 fork；非 Linux 平台返回明确错误)
数据库默认位置: ~/.innate/personal.db (可通过 INNATE_DB 环境变量或 --db 覆盖)
平台: Linux / macOS / Windows (WSL)；Daemon 仅 Linux

文档

docs/Innate-设计文档-v4.5.1.md — 完整系统设计 (权威基线)
skills/innate-memory/SKILL.md — Agent Skill 元数据与使用规范

开发

# 编译
cd core && cargo build --release

# 运行全量测试
cd core && cargo test

# 运行单个测试
cd core && cargo test test_add_and_recall

# 检视默认知识库
innate inspect

测试按职责分组: add_and_recall · spark_and_promote · record_state_machine · invalidate_cascade · inspect_returns_counts · evolve_smoke + 3 个 utils 测试。

License

MIT

innate 0.1.2

Innate — 自成长 Agent 程序性知识层

核心闭环

安装

Rust 核心 (唯一运行时)

Python SDK

TypeScript SDK

MCP 服务 (Claude Code / Claude Desktop)

Daemon (Linux only)

接入 Agent (MCP 配置)

步骤

Agent 工作规范

快速开始

Python SDK

TypeScript SDK

CLI 子命令一览

recall 输出格式

inspect 输出

MCP 工具 (innate mcp 暴露的 13 个工具)

系统架构

核心特性

兼容性

文档

开发

License

`recall` 输出格式

`inspect` 输出

MCP 工具 (`innate mcp` 暴露的 13 个工具)