convez.ai
MCP Server
vima-tech

Innate

vima-tech/Innate

Ver no GitHub
InicialPluginScore · de 0 a 100

Self-growing procedural knowledge layer for AI agents. Rust MCP server + CLI — recall relevant knowledge before tasks, record outcomes after, distill experience into reusable insights. Works with Claude Code, Codex, opencode.

Instalação

$npx convez-ai vima-tech/Innate

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
2
Forks
0
Acompanhando
0
Saúde
37%
Último commit
há 1 semana
Versão
v0.2.0
Issues abertas
0
Contribuidores
1

README

A tradução para o português deste README ainda está na fila.

Innate — Self-Growing Procedural Knowledge Layer

中文文档

One-line pitch: An embeddable, self-growing, engine-swappable procedural knowledge layer for AI agents. It does not orchestrate (neutral to LangGraph / Claude Code / raw API calls). It solves one thing — assembling the most relevant, precise knowledge within a token budget, and letting that knowledge evolve through real use.

Innate does not manage declarative memory ("what the world looks like / user preferences") or a static skill repository written once and never updated. It manages procedural knowledge — "how to do things, which approach works better in this context." Every knowledge chunk is evaluated by real outcomes from the moment it enters the store: effective chunks gain confidence, stale ones decay and archive, sparks incubate and promote, and the whole library gets sharper with use.


Installation

One-line install (Linux / macOS)

curl -fsSL https://innate.mengkai.ren/ | sh

Downloads the pre-built binary for your platform, verifies the checksum, places it in ~/.local/bin, and runs innate install to configure agent integration — all in one step.

Options:

# Pin a specific version
curl -fsSL https://innate.mengkai.ren/ | INNATE_VERSION=0.1.8 sh

# Skip agent setup (binary only)
curl -fsSL https://innate.mengkai.ren/ | NO_INNATE_SETUP=1 sh

# Custom install directory
curl -fsSL https://innate.mengkai.ren/ | INNATE_DIR=/usr/local/bin sh

Other install methods

# Rust
cargo install innate

# Python installer (downloads pre-built binary, no Rust required)
pip install innate-ai

# npm installer (downloads pre-built binary, no Rust required)
npm install -g @vima_tech/innate

# Build from source
cd core && cargo build --release
cp target/release/innate ~/.local/bin/

Verify the install:

innate inspect

Configure agent integration

After the binary is on your PATH, run the interactive wizard to configure the MCP server and install the innate-memory agent skill (skipped automatically by the one-line installer above):

innate install

Detects Claude Code, Codex CLI, and opencode automatically.

Let an agent install for you

Paste the following prompt into Claude Code (or any agent with shell access):

Install Innate by running: curl -fsSL https://innate.mengkai.ren/ | sh
This downloads the binary, verifies the checksum, and configures the MCP server and agent skill automatically.
Verify with `innate inspect` when done.

Python SDK (programmatic use)

pip install innate-py

TypeScript SDK (programmatic use)

npm install @innate/sdk

MCP server (Claude Code / Claude Desktop)

Add to .claude/settings.json:

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

Once configured, the agent can call innate_recall, innate_record, and other MCP tools directly — no CLI invocation needed.

Daemon (Linux only)

Background process that watches log directories and JSON hook events and bridges them into the knowledge layer:

innate daemon start --watch /path/to/log/dir
innate daemon status
innate daemon stop

The daemon calls the innate CLI via subprocess and never opens the database directly. Its state (file offsets, processed events, session traces) is stored in a separate daemon_state.sqlite.

Uninstall

innate uninstall              # interactive — keeps data
innate uninstall -y           # skip prompts, keep data
innate uninstall -y --purge-data  # remove everything including ~/.innate/

Quick Start

# 1. Add a knowledge chunk
innate add "List comprehensions are more readable than map/filter in Python" \
  --kind note --trigger "python list processing"

# 2. Recall knowledge (returns top chunks + trace_id)
innate recall "python list optimization" --budget 2000 --format json

# 3. Close the trace (complete the experience loop)
innate record <trace_id> --outcome ok --used <chunk_id1>,<chunk_id2>

# 4. Trigger growth (distil + curate)
innate evolve --trigger manual

# 5. Health check
innate inspect

Core Loop

Five loops must all be complete — any missing one means it is not a "knowledge layer":

LoopPath
Recallquery → recall → context (dual-vector cosine + scalar filter, synchronous pure math)
Observecontext → use → trace (records which chunks were used and the outcome)
Growtrace → distil → pending (offline distillation of new experience)
Governusage → confidence → curate (EMA confidence update + archive)
Safetypending / archived / no hard delete (default sanitize hook, blacklist + red action)

The default synchronous recall path never calls any LLM — Innate is the librarian, not the reader and editor. Only when the caller explicitly enables the optional Refiner does trim/adapt execute.


MCP Integration

The recommended way to connect an agent is through the MCP server.

Agent workflow protocol

After configuration, give your agent the following protocol:

OperationMCP tool
Agent may call freelyinnate_recall · innate_record · innate_evolve · innate_inspect
Confirm before callinginnate_add · innate_spark
Human governance onlyinnate_approve · innate_archive · innate_invalidate · innate_restore · innate_mature_spark · innate_promote_spark · innate_drop_spark

Workflow

  • Call innate_recall(query="<task intent>") before each task; incorporate the result into your plan
  • Call innate_record(trace_id=..., outcome="ok"|"fail") after each task to close the trace
  • When you find experience worth keeping, distil it and confirm with the user before calling innate_add or innate_spark
  • When knowledge seems stale, propose governance — never execute governance actions autonomously
  • Call innate_evolve(trigger="manual") at the end of a session to trigger distillation

Python SDK

from innate import KnowledgeBase

kb = KnowledgeBase("personal.db")  # or set INNATE_DB env var

# Add knowledge
note_id = kb.add("insight text", kind="note", trigger_desc="when to use this")
spark_id = kb.spark("a hypothesis to explore", trigger_desc="related context")

# Recall (synchronous, pure math)
ctx = kb.recall("task description", budget=6000, include_sparks=True)
for chunk in ctx.knowledge:
    print(chunk["id"], chunk["content"])

# Record usage
kb.record(ctx.trace_id, outcome="ok", used=[note_id], output_summary="solved X")

# Grow
result = kb.evolve(trigger="manual")

# Governance (human-initiated)
kb.approve(pending_id)
kb.archive(note_id, reason="stale")
kb.invalidate(note_id, reason="logic error")
kb.restore(archived_id)

# Spark lifecycle
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="disproved")

# Health check
report = kb.inspect()

TypeScript SDK

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

// CLI subprocess mode (synchronous, suitable for scripts)
const kb = new KnowledgeBase({ dbPath: "personal.db" });

const ctx = kb.recall("task description", { budget: 6000 });
kb.record(ctx.trace_id, { outcome: "ok", used: [chunkId] });
kb.add("insight text", { kind: "note", triggerDesc: "when to use this" });
kb.evolve("manual");
const report = kb.inspect();

// MCP client mode (async, suitable for agent integration)
const client = new McpClient({ dbPath: "personal.db" });
await client.initialize();

const result = await client.recall("task description", { budget: 6000 });
await client.record(result.trace_id, { outcome: "ok" });
await client.add("new insight", { kind: "note" });
await client.inspect();

client.close();

CLI Reference

The CLI is a thin wrapper over the SDK public API — it adds no knowledge-layer logic beyond argument parsing and output formatting.

CommandDomainOptions
innate recall <query>Read--budget · --top · --include-sparks · --format text|json
innate record <trace_id>Write--outcome ok|fail|unknown · --used · --output-summary · --nomination · --source
innate evolveGrow--trigger manual|scheduled|threshold
innate inspectDebugHealth check: 5 signals + current parameters
innate add <content>Write--kind note|skill · --trigger · --anti-trigger · --skill-name · --source · --depends-on <id> (repeatable) · --dep-kind hard|soft
innate spark <content>Spark--trigger
innate mature-spark <id> <to>Governto: sprouting|incubating (forward only)
innate promote-spark <id>Govern--to note|skill
innate drop-spark <id>Govern--reason
innate approve <id>Governpending → active
innate archive <id>Govern--reason
innate invalidate <id>Govern--reason (archive + blacklist)
innate restore <id>Governarchived → active; if previously invalidated, also clears hash blacklist
innate mcpIntegrateStart MCP stdio server (JSON-RPC 2.0) for Claude Code / Desktop
innate installSetupInteractive wizard — configure agents, install binary, install skill
innate uninstallSetupRemove Innate from all configured agents and PATH
innate daemon startIntegrateBackground log/hook watcher --watch <dir> (Linux only)
innate daemon statusIntegrateShow daemon status and error stats
innate daemon stopIntegrateStop a running daemon
innate backup run|status|list|pruneOpsCloudflare R2 backup/restore/list/prune
innate upgradeOpsSelf-update from GitHub Releases --version · --check
innate migrateOpsApply schema migrations up to the current version
innate vacuumOpsCheckpoint WAL + VACUUM to reclaim space after curate
innate hook stopIntegrateProcess a Claude Code Stop payload from stdin into session events

MCP tools (14 tools exposed by innate mcp)

MCP ToolCapability
innate_recallRecall knowledge — call FIRST at task start
innate_recordRecord trace outcome — call LAST after task completion
innate_addWrite a knowledge chunk (optional depends_on[] + dep_kind to declare hard/soft deps)
innate_sparkCreate a spark (idea / hypothesis)
innate_evolveTrigger growth — call at session end
innate_inspectHealth check
innate_approve / innate_archive / innate_invalidate / innate_restoreGovernance
innate_mature_spark / innate_promote_spark / innate_drop_sparkSpark lifecycle
innate_backupTrigger a Cloudflare R2 backup

Architecture

Four access modules share one Rust KnowledgeBase core:

MCP    (innate mcp)          ──────────────────────────┐
CLI    (innate <cmd>)         ──────────────────────────┤──> KnowledgeBase Core ──> SQLite
SDKs   (Python / TypeScript)  ──> CLI ─────────────────┤
Daemon (innate daemon start)  ──> CLI ─────────────────┘
ModuleImplementationNotes
MCPDirect Core callJSON-RPC 2.0 over stdio; 14 tools; for Claude Code / Claude Desktop
CLIDirect Core callclap thin wrapper; full public API as CLI commands
Python SDKsubprocess → CLIinnate-py, zero extra dependencies
TypeScript SDKsubprocess → CLI + async MCP client@innate/sdk, Node.js 18+
Daemonsubprocess → CLIBackground log/JSON hook watcher; idempotent events; session trace; error stats; tail resumption (Linux only)
Innate System
├── Rust core (core/)
│   ├── KnowledgeBase (lib)     8 public APIs, SQLite + pure-Rust cosine similarity
│   ├── CLI (innate <cmd>)      clap thin wrapper → KnowledgeBase calls
│   ├── MCP Server (innate mcp) JSON-RPC 2.0 over stdio, 14 MCP tools
│   └── Daemon (innate daemon)  background log/hook watcher, subprocess → CLI (Linux only)
│
├── Vector search               f32 BLOB storage + full-scan cosine similarity (zero native extensions)
│   ├── vec_content             content vector (BLOB)
│   └── vec_trigger             trigger vector (BLOB)
│
├── SDKs
│   ├── sdks/python/            innate-py  — subprocess → CLI, zero extra dependencies
│   └── sdks/typescript/        @innate/sdk — CLI subprocess + async MCP client
│
└── skills/innate-memory/       SKILL.md (MCP tools primary, CLI fallback)

Core Features

  • Dual-vector recall: content_vec + trigger_vec, fused ranking with configurable w_content / w_trigger / w_confidence weights
  • Confidence-driven ranking: EMA update + recency weighting (explicit signals) + time decay — knowledge improves with use
  • Zero native extensions: vectors stored as f32 BLOBs, cosine similarity in pure Rust — no sqlite-vec or C extension required
  • Native MCP integration: innate mcp exposes 14 tools, works out of the box with Claude Code and Claude Desktop
  • Hard-dep fail-closed: if a hard dependency is unavailable or archived at recall time, the entire seed is discarded — no partial closures returned
  • Zero autonomous behavior: the SDK never acts on its own; all growth is externally triggered (evolve trigger: manual / scheduled / threshold)
  • Sanitize three-state contract: hook returns (cleaned, action), action ∈ {allow, redact, discard}; discard rejects the write, redact caps confidence at 0.4
  • Spark independent lifecycle: maturity = seed → sprouting → incubating, exits only on promote / drop; not included in confidence ranking, not archived by low score
  • Atomic dual-vector write: chunk + content_vec + trigger_vec written in a single BEGIN IMMEDIATE transaction; any failure rolls back
  • Auto schema migration: applies incremental migrations on startup; runs schema.sql directly on an empty database

Compatibility

  • Core runtime: Rust 1.70+ (bundled SQLite, zero external runtime dependencies)
  • Python SDK: Python 3.8+ (subprocess, zero extra dependencies)
  • TypeScript SDK: Node.js 18+ (child_process, zero extra dependencies)
  • Daemon: Linux only (requires /proc and fork; returns a clear error on non-Linux platforms)
  • Default database: ~/.innate/data/personal.db (overridable via INNATE_DB env var or --db flag)
  • Platforms: Linux / macOS / Windows; Daemon is Linux only

Documentation


Development

# Build
cd core && cargo build --release

# Run all tests
cd core && cargo test

# Run a specific test
cd core && cargo test test_add_and_recall

# Inspect the default knowledge base
innate inspect

Tests (104 total, all passing) are grouped by responsibility under core/src/tests/: basics · feedback · governance · distillation · distill_failures · evolve_retries · reliability · restoration.


License

MIT

Ver o original no GitHub

Bom para

Relacionados