npm - mio-agent-runtime - Versions diffs - 0.5.5 → 0.5.7 - Mend

mio-agent-runtime 0.5.5 → 0.5.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (2) hide show

package/README.md +167 -234
package/package.json +1 -1

package/README.md CHANGED Viewed

@@ -1,309 +1,242 @@
-# Mio Agent Runtime
+# mio-agent-runtime
-> 让所有 AI Agent 共享记忆、观察行为、积累经验——安装一次，无感增强。
+> Your AI agents forget everything between sessions. Mio fixes that.
-Mio 是 **Agent Control Plane**：不替代任何 Agent，而是为它们提供统一的智能层。
-安装到 Codex、OpenCode、Hermes、WorkBuddy 后，所有 Agent 的决策、错误和结果自动进入共享记忆，跨 Agent 复用经验。
+Mio is a drop-in intelligence layer for Codex, OpenCode, Hermes, and WorkBuddy. Install once, and every agent you use starts remembering decisions, learning from mistakes, and sharing experience across tools — without any workflow changes.
 ```
-┌─────────────────────────────────────────────┐
-│              用户的日常工具                    │
-│  Codex  ·  OpenCode  ·  Hermes  ·  WorkBuddy │
-└──────────────────┬──────────────────────────┘
-                   │ MCP
-         ┌─────────┴─────────┐
-         │  Mio Intelligence  │
-         │                   │
-         │  Memory           │  决策、上下文、问题记录
-         │  Observer         │  被动观察 Agent 行为
-         │  Policy           │  高风险操作拦截
-         │  Experience       │  跨 Agent 经验复用
-         │  Ideas            │  记忆驱动的创意生成
-         │  Evolution        │  生态级优化建议
-         └───────────────────┘
+  Codex ─┐
+OpenCode ─┤── MCP ──> Mio Intelligence Core
+  Hermes ─┘            ├─ Memory      decisions, context, problems
+                       ├─ Observer    passive session monitoring
+                       ├─ Policy      risk checks before dangerous ops
+                       ├─ Experience  cross-agent knowledge transfer
+                       ├─ Ideas       memory-powered idea generation
+                       └─ Evolution   ecosystem-level optimization
 ```
 ---
-## 快速开始
+## Install
 ```bash
-# 1. 全局安装
 npm install -g mio-agent-runtime
-# 2. 初始化
 mio init
-# 3. 接入你使用的 Agent（可多选）
-mio install codex        # Codex Desktop / CLI
-mio install opencode     # OpenCode
-mio install hermes       # Hermes (Nous)
-mio install workbuddy    # WorkBuddy
-# 4. 查看状态
+mio install codex          # or: opencode, hermes, workbuddy
 mio status
 ```
-安装完成后**重启对应 Agent**，Mio 即自动生效。无需改变任何使用习惯。
+Restart your agent after install. That's it.
 ---
-## 核心能力
+## What it actually does
-### 记忆 — `mio.memory.*`
+**Without Mio**, every agent starts from zero each session. Your Codex forgets why you chose Postgres over Redis. Your OpenCode re-discovers the same config bug. Your WorkBuddy re-reads the same ADR you already explained.
-| 工具 | 功能 |
-|------|------|
-| `mio.memory.record` | 记录决策、上下文、问题、笔记 |
-| `mio.memory.query` | 按关键词/标签/类型检索历史记忆 |
-| `mio.memory.analyze` | 分析记忆质量：类型分布、重复检测、低质量记录 |
-| `mio.memory.archive` | 归档不再需要的记忆（可恢复） |
-| `mio.memory.migrate` | 在项目级和全局级之间迁移记忆 |
+**With Mio**, the first agent to solve a problem records the solution. The next agent — any agent — finds it automatically.
-### 观察 — `mio.observer.*`
+```
+  Session 1 (Codex)                    Session 2 (OpenCode)
+  ─────────────────                    ──────────────────
+  "Why not Redis?"                     "How should we cache?"
+  → records decision                   → queries memory
+  → Mio saves it                       → finds the Redis answer
+                                       → skips the dead end
+```
-| 工具 | 功能 |
-|------|------|
-| `mio.observer.ingest` | 上报 Agent 事件：工具调用、错误、重试、任务结果 |
-| `mio.observer.subscribe` | 订阅特定项目/事件类型的实时通知 |
-| `mio.observer.digest` | 拉取自上次以来的新事件 |
+---
-### 策略 — `mio.policy.*`
+## CLI Reference
-| 工具 | 功能 |
-|------|------|
-| `mio.policy.check` | 执行高风险操作前检查历史失败率和风险等级 |
+| Command | Description |
+|---------|-------------|
+| `mio init` | Create `~/.mio-intelligence` and default config |
+| `mio install <host>` | Wire MCP + rules + observer into a host |
+| `mio mcp` | Start MCP server (stdio, for agent integration) |
+| `mio status` | Show runtime state, adapter status, observer PID |
+| `mio agents` | List installed hosts |
+| `mio observe` | Foreground session monitor (Ctrl+C to stop) |
+| `mio observe --start` | Start background observer daemon |
+| `mio observe --stop` | Stop background daemon |
+| `mio observe --status` | Check daemon state |
+| `mio observe --once` | Run one collection cycle |
+| `mio --json <cmd>` | Any command outputs JSON |
-### 经验 — `mio.experience.*`
+**What `mio install` does under the hood:**
-| 工具 | 功能 |
-|------|------|
-| `mio.experience.reuse` | 记录一次跨 Agent 经验复用（来源→目标→是否改善结果） |
-| `mio.experience.confirm` | 人工确认自动声明的复用记录 |
-| `mio.experience.list` | 查询复用证据，按状态/Agent 过滤 |
+```
+mio install codex
+  |
+  +-- Writes MCP server config to ~/.codex/config.json
+  +-- Injects usage rules into AGENTS.md
+  +-- Backfills last 24h of session history
+  +-- Starts background passive observer
+```
-### 任务 — `mio.task.*`
+---
-| 工具 | 功能 |
-|------|------|
-| `mio.task.route` | 根据历史经验为任务推荐最佳 Agent |
-| `mio.task.record_outcome` | 记录任务执行结果（成功/失败/中止） |
+## MCP Tools (22 tools)
-### Agent — `mio.agent.*`
+### Memory
-| 工具 | 功能 |
-|------|------|
-| `mio.agent.register` | 注册 Agent 元数据（名称、能力、宿主） |
-| `mio.agent.list` | 列出已注册的 Agent |
-| `mio.agent.report` | 查询指定 Agent 的能力报告和行为摘要 |
+| Tool | Required | Optional | Description |
+|------|----------|----------|-------------|
+| `mio.memory.record` | `content` | `kind`, `tags`, `project`, `scope`, `source` | Save a decision, context, problem, or note |
+| `mio.memory.query` | `query` | `project`, `limit`, `kind`, `tags`, `scope` | Search memory by keyword, tag, or type |
+| `mio.memory.analyze` | — | `project`, `limit` | Audit quality: duplicates, low-quality, type distribution |
+| `mio.memory.archive` | `ids` | `project`, `restore`, `reason` | Archive records (recoverable) |
+| `mio.memory.migrate` | `ids`, `scope` | `project`, `reason` | Move between project and global layers |
-### 创意 — `mio.idea.*`
+### Observer
-| 工具 | 功能 |
-|------|------|
-| `mio.idea.generate` | 基于记忆库，用 SCAMPER / 类比 / 第一性原理 / 随机刺激 / 约束反转 五种策略生成创意 |
-| `mio.idea.list` | 查询已保存的创意，按目标/策略/时间段过滤 |
+| Tool | Required | Optional | Description |
+|------|----------|----------|-------------|
+| `mio.observer.ingest` | `trace_id`, `event_type` | `payload`, `outcome`, `agent`, `host`, `project` | Report tool calls, errors, retries, task outcomes |
+| `mio.observer.subscribe` | — | `eventTypes`, `project`, `topic`, `ttlDays` | Subscribe to event stream by type/project |
+| `mio.observer.digest` | — | `project`, `eventTypes`, `limit` | Pull new events since last digest |
-### 进化 — `mio.evolution.*`
+### Policy
-| 工具 | 功能 |
-|------|------|
-| `mio.evolution.report` | 生成生态系统分析报告 |
-| `mio.evolution.suggest` | 输出可执行的优化建议（带 nextAction 和 impact） |
+| Tool | Required | Optional | Description |
+|------|----------|----------|-------------|
+| `mio.policy.check` | `action` | `project`, `context` | Pre-flight risk check against historical failure data |
-### 验证 — `mio.phase0.*`
+### Experience
-| 工具 | 功能 |
-|------|------|
-| `mio.phase0.report` | 生成 Phase 0 跨 Agent 验证报告（JSON / Markdown） |
+| Tool | Required | Optional | Description |
+|------|----------|----------|-------------|
+| `mio.experience.reuse` | `sourceAgent`, `targetAgent`, `experienceId`, `reuse`, `behaviorChanged`, `outcomeImproved` | `notes`, `project` | Record cross-agent experience reuse with evidence |
+| `mio.experience.confirm` | `id` | `confirmedBy`, `notes`, `outcomeImproved` | Human-confirm an auto-claimed reuse record |
+| `mio.experience.list` | — | `status`, `targetAgent`, `limit`, `project` | Query reuse evidence, filter by status |
----
+### Task
-## 支持的 Agent 宿主
+| Tool | Required | Optional | Description |
+|------|----------|----------|-------------|
+| `mio.task.route` | `task` | `project`, `scope`, `limit` | Recommend best agent for a task based on history |
+| `mio.task.record_outcome` | — | (event-based) | Record task success/failure/abort |
-### Codex (OpenAI)
+### Agent
-- **接入方式**：修改 `~/.codex/config.json`，注入 `mcpServers.mio`
-- **工作流增强**：AGENTS.md 规则注入 → Agent 自动在决策前后调用 Mio
-- **被动观察**：不依赖，Codex 默认主动调用 MCP 工具
+| Tool | Required | Optional | Description |
+|------|----------|----------|-------------|
+| `mio.agent.register` | — | (metadata) | Register agent capabilities and host |
+| `mio.agent.list` | — | — | List registered agents |
+| `mio.agent.report` | — | (agent ID) | Query agent behavior summary |
-### OpenCode
+### Ideas
-- **接入方式**：修改 `~/.config/opencode/opencode.json`（MCP）+ `~/.config/opencode/AGENTS.md`（规则）
-- **被动观察**：`mio observe` 通过 `opencode db` 增量读取会话数据库，自动提取任务结果和工具错误，写回 `<workspace>/AGENTS.md` 的 `MIO_CONTEXT` 块
-- **增量机制**：按 `part` 表的 `rowid` 游标，只传输 `text` / `tool` 类型，首次只回填 24h 内数据
+| Tool | Required | Optional | Description |
+|------|----------|----------|-------------|
+| `mio.idea.generate` | `goal` | `context`, `constraints` | Generate ideas using 5 strategies: SCAMPER, analogy, first-principles, random-stimulus, constraint-inversion |
+| `mio.idea.list` | — | `goal`, `strategy`, `period` | Query saved ideas |
-### Hermes (Nous)
+### Evolution
-- **接入方式**：`hermes mcp add mio-intelligence --command node --args <server>`
-- **被动观察**：增量读取 `<LocalAppData>/hermes/state.db`（`messages.id` 自增游标），无需调用 hermes CLI
-- **写回策略**：仅当会话发生在真实 git 仓库时写回 `AGENTS.md`，避免污染用户主目录
+| Tool | Required | Optional | Description |
+|------|----------|----------|-------------|
+| `mio.evolution.report` | — | `project` | Ecosystem analysis report |
+| `mio.evolution.suggest` | — | `project` | Actionable optimization suggestions with nextAction + impact |
-### WorkBuddy
+### Validation
-- **接入方式**：写入 `~/.workbuddy/mcp.json` + `~/.workbuddy/mcp-approvals.json`
-- **规则注入**：写入 `~/.workbuddy/CODEBUDDY.md`（用户级）+ `<workspace>/AGENTS.md`（项目级）
-- **被动观察**：监听 `~/.workbuddy/projects/**/*.jsonl`，自动提取任务结果，写回 `<workspace>/.workbuddy/memory/YYYY-MM-DD.md`
-> 所有宿主的被动观察器共享同一套 schema，数据统一存入 `MIO_HOME`，实现跨 Agent 经验复用。
+| Tool | Required | Optional | Description |
+|------|----------|----------|-------------|
+| `mio.phase0.report` | — | `project`, `format` | Cross-agent value validation report (JSON / Markdown) |
 ---
-## 被动观察器
-被动观察器是 Mio 的核心差异化能力：**不依赖 Agent 主动调用，自动采集行为数据。**
-```text
-Agent 会话日志
-      ↓
-  mio observe
-      ↓
-  ┌──────────────────┐
-  │ 提取 task_outcome │
-  │ 提取 tool error   │
-  │ 生成任务摘要      │
-  └────────┬─────────┘
-           ↓
-  MIO_HOME/traces.jsonl   ← 统一行为数据
-  MIO_HOME/memory.jsonl   ← 自动记忆
-           ↓
-  写回 Agent 原生记忆文件  ← 单 Agent 闭环
-```
-### 后台守护进程
-```bash
-mio observe --start    # 启动后台守护
-mio observe --stop     # 停止
-mio observe --status   # 查看状态
-mio observe --once     # 执行一次采集周期
-mio observe            # 前台持续监听（Ctrl+C 停止）
-```
+## Supported Hosts
-### 增量与去重
+| Host | Config Location | Observer Method | Write-back |
+|------|----------------|-----------------|------------|
+| **Codex** | `~/.codex/config.json` | Not needed (agent calls MCP directly) | AGENTS.md rules |
+| **OpenCode** | `~/.config/opencode/opencode.json` | `opencode db` incremental read | `MIO_CONTEXT` block in AGENTS.md |
+| **Hermes** | `hermes mcp add` | `state.db` cursor (no CLI needed) | AGENTS.md (git repos only) |
+| **WorkBuddy** | `~/.workbuddy/mcp.json` | Tails `projects/**/*.jsonl` | `CODEBUDDY.md` + workspace AGENTS.md |
-- 已处理的文件偏移记录在 `MIO_HOME/observe-state.json`，不会重复写入
-- 只回填最近 24h 内更新的会话，避免历史灌入
+### How passive observation works
----
+Most agents don't call memory tools on their own, even when rules are injected. The passive observer solves this by reading session logs directly:
-## CLI 命令
-```text
-mio init                    初始化 MIO_HOME 目录结构
-mio mcp                     启动 MCP Server（stdio 模式，供 Agent 调用）
-mio install <host>          接入指定 Agent（codex|opencode|workbuddy|hermes）
-mio status                  显示运行时状态和所有 Adapter 状态
-mio agents                  列出已安装的 Agent
-mio observe                 观察器管理（见上方）
-mio --json status           机器可读的状态输出
-mio --json agents           机器可读的 Agent 列表
 ```
-### `mio install` 做了什么
-```text
-mio install codex
-      │
-      ├── 修改 ~/.codex/config.json → 添加 mio MCP Server
-      ├── 注入 AGENTS.md 规则 → Agent 自动调用 Mio
-      ├── 执行一次历史回填 → 被动观察已有会话
-      └── 启动后台观察器 → 持续采集
+Agent session logs
+      |
+  mio observe (background daemon)
+      |
+  +-- Extracts task_outcome, errors, summaries
+  +-- Writes to MIO_HOME/traces.jsonl + memory.jsonl
+  +-- Writes summary back to agent's native memory file
+      |
+  Next session: agent sees Mio's notes without calling any tool
 ```
+- **Incremental**: file offsets tracked in `observe-state.json`, no duplicates
+- **Scoped**: only backfills sessions updated in last 24h
+- **Per-host**: each adapter reads its own format (JSONL / SQLite / DB CLI)
 ---
-## MIO_HOME 目录结构
+## MIO_HOME
-默认 `~/.mio-intelligence`，可通过 `MIO_HOME` 环境变量覆盖。
+Default: `~/.mio-intelligence` (override with `MIO_HOME` env var).
-```text
+```
 ~/.mio-intelligence/
-├── config.json              运行时配置（已安装的 Agent 列表）
-├── memory.jsonl             记忆存储（决策、上下文、问题）
-├── traces.jsonl             行为追踪（任务结果、工具调用）
-├── experience-reuse.jsonl   跨 Agent 经验复用记录
-├── ideas.jsonl              生成的创意想法
-├── suggestions.jsonl        进化建议
-├── observe-state.json       观察器增量游标
-├── observe.pid              后台观察器进程 ID
-└── logs/                    运行日志
+    config.json              runtime config + installed hosts
+    memory.jsonl             decisions, context, problems
+    traces.jsonl             agent behavior events
+    experience-reuse.jsonl   cross-agent reuse evidence
+    ideas.jsonl              generated ideas
+    suggestions.jsonl        evolution suggestions
+    observe-state.json       observer increment cursors
+    observe.pid              background daemon PID
+    logs/                    runtime logs
 ```
 ---
-## 架构定位
-Mio 不是又一个 AI 助手，而是 **Agent 的控制平面**。
-```text
-传统模式（每个 Agent 独立）：
-  Codex     OpenCode     Hermes     WorkBuddy
-  (各自记忆)  (各自记忆)   (各自记忆)   (各自记忆)
-Mio 模式（统一智能层）：
+## Architecture
-  Codex     OpenCode     Hermes     WorkBuddy
-     \        |         /          /
-      └───────┴────────┴──────────┘
-                 |
-          Mio Intelligence
-          ┌──────┴──────┐
-          │ Memory       │  跨 Agent 共享
-          │ Observer     │  行为自动采集
-          │ Policy       │  风险统一管理
-          │ Experience   │  复用证据链
-          │ Ideas        │  记忆驱动创意
-          │ Evolution    │  生态优化
-          └─────────────┘
 ```
-### 核心差异
-| 维度 | Agent Memory | Mio Control Plane |
-|------|-------------|-------------------|
-| 作用域 | 单 Agent | 多 Agent 生态 |
-| 数据采集 | 依赖 Agent 主动调用 | 被动观察 + 主动调用 |
-| 经验流动 | 无 | 跨 Agent 复用 + 证据验证 |
-| 风险管理 | 无 | 统一策略检查 |
-| 优化对象 | 单个 Agent 的记忆 | 整个 Agent 生态的质量和效率 |
----
-## 版本要求
-| 版本 | 能力 |
-|------|------|
-| `< 0.3.6` | 仅主动 MCP 规则注入 |
-| `≥ 0.3.6` | 被动观察 + 无感存取 |
-| `≥ 0.5.0` | 创意生成 + 进化建议 |
-```bash
-npm install -g mio-agent-runtime@latest
+Before Mio:
+  Codex ──── (forgets everything)
+  OpenCode ── (starts from zero)
+  Hermes ──── (isolated memory)
+  WorkBuddy ─ (no continuity)
+After Mio:
+  Codex ─┐
+OpenCode ─┤        Mio Intelligence Core
+  Hermes ─┼────>   + Memory ........... shared knowledge base
+WorkBuddy ─┘       + Observer ......... automatic data collection
+                    + Policy ........... risk management
+                    + Experience ........ cross-agent reuse with evidence
+                    + Ideas ............ memory-powered creativity
+                    + Evolution ........ ecosystem optimization
 ```
----
-## 开发
+| | Standalone Agent Memory | Mio Control Plane |
+|---|---|---|
+| **Scope** | Single agent | Multi-agent ecosystem |
+| **Collection** | Agent must call tools | Passive observation + active calls |
+| **Knowledge flow** | Isolated | Shared with reuse evidence |
+| **Risk management** | None | Unified policy checks |
+| **Optimization** | Per-agent | Ecosystem-wide |
-```bash
-git clone https://github.com/your-org/akemi-mio.git
-cd akemi-mio
-node --check server/mio-intelligence-mcp/index.js   # 语法检查
-npm run check                                         # 全量检查
-```
+---
-### 发布流程
+## Version History
-```bash
-# 1. 编辑 server/mio-intelligence-mcp/index.js
-# 2. 复制到 npm 包目录
-cp server/mio-intelligence-mcp/index.js tmp/mio-agent-runtime/package/server/mio-intelligence-mcp/index.js
-# 3. 更新版本号
-# 4. 发布
-cd tmp/mio-agent-runtime/package && npm publish
-```
+| Version | Milestone |
+|---------|-----------|
+| < 0.3.6 | Active MCP rule injection only |
+| >= 0.3.6 | Passive observation + seamless read/write |
+| >= 0.5.0 | Idea generation + evolution suggestions |
+| >= 0.5.6 | Rewritten documentation |
 ---

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "mio-agent-runtime",
-  "version": "0.5.5",
+  "version": "0.5.7",
   "description": "Mio Agent Runtime installer and MCP intelligence layer",
   "license": "MIT",
   "type": "commonjs",