` even though the sidebar session title loads correctly and the bridge reports `running / initialized`. This is likely a bridge IPC timing issue or APFS/SQLite WAL checkpoint race on cold start β needs native debugging. The non-restart session-switch recall test still validates #490 behavior on macOS.\n\n---\n\n## Documentation\n\n- [Getting Started](docs/getting-started.md)\n- [Architecture](docs/architecture.md)\n- [Configuration](docs/configuration.md)\n- [MCP Integration](docs/mcp-integration.md)\n- [Developer Guide](docs/developer-guide.md)\n- [Internal Alpha Smoke](docs/internal-alpha-smoke.md)\n\n---\n\n## License\n\n[MIT License](LICENSE)\n\n---\n\n## Contributing\n\nContributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details.\ntest\n"}, "4f0e4b608b4e387e25d118c68fc740ac3a178aaf": {"t": 1785771665.4658759, "n": 12757, "h": "d4c907dfb99f861b", "c": "# MiQi\n\n\n πββ¬πͺΆ A lightweight, extensible personal AI agent framework with a modern desktop interface\n
\n\n\n ![\"Python](\"https://img.shields.io/badge/python-3.11%20%7C%203.12-blue\")
\n ![\"Node.js](\"https://img.shields.io/badge/node.js-20+-green\")
\n ![\"Development](\"https://img.shields.io/badge/status-alpha-orange\")
\n ![\"MIT](\"https://img.shields.io/badge/license-MIT-green\")
\n
\n\n---\n\n## Overview\n\nMiQi Desktop is an Electron-based desktop application that provides a modern graphical interface for the MiQi AI agent. It combines powerful AI agent capabilities with an intuitive user interface, supporting chat interaction, memory management, task scheduling, and more.\n\n\n### Core Positioning\n\n- π― **Personal AI Agent** β not just a chatbot: persistent memory, learned skills, file operations, and scheduled tasks\n- π§ **Highly Extensible** β MCP protocol for external tools, custom skills, and pluggable LLM providers\n- π₯οΈ **Native Desktop Experience** β Electron with system-level integration (WSL2 sandbox, filesystem operations)\n- π **Local-First** β all data stored locally; non-destructive file editing with versioned snapshots\n- π **Typed Application Protocol** β typed AppServer with JSON Schema catalog, method stability tracking, and handler-boundary validation\n\n### Tech Stack\n\n| Layer | Technology | Version |\n|-------|-----------|---------|\n| Desktop Framework | Electron | 35.2 |\n| Frontend UI | React + TypeScript | 19.1 / 5.8 |\n| CSS | Tailwind CSS 4 | 4.x |\n| Component Library | Radix UI + Lucide Icons | β |\n| Python Runtime | Python (asyncio) | 3.11+ |\n| Data Validation | Pydantic v2 | 2.12+ |\n| CLI Framework | Typer | 0.20+ |\n| Build (Desktop) | electron-vite + electron-builder | 3.1 / 26.0 |\n| Build (Python) | PyInstaller + Hatchling | 6.20+ |\n\n---\n\n## Key Features\n\n| Feature | Description |\n|---|---|\n| **Smart Chat** | Natural language conversation with streaming responses and tool-call progress |\n| **Multi-Provider** | OpenAI, Anthropic, Gemini, OpenRouter, DeepSeek, and more β with provider resilience |\n| **Typed Protocol** | Typed AppServer with method specs, JSON Schema catalog, and handler-boundary validation |\n| **Memory System** | Long-term memory snapshots, self-improvement lessons, and cross-session recall |\n| **Task Scheduler** | Cron-based scheduled tasks with timezone support |\n| **Skill System** | Create, upload, and manage agent skills; SkillHub registry integration |\n| **Plugin Ecology** | MCP servers, plugins, and marketplace with deterministic catalog |\n| **Sandbox Execution** | bwrap-based sandbox with LANDLOCK filesystem rules, streaming I/O, and process lifecycle |\n| **File Management** | Workspace FS with watch, fuzzy search, snapshot/versioning, and non-destructive editing |\n| **Replay & Debug** | Deterministic replay of turns, timeline, and messages for inspection |\n| **Session Management** | Browse, search, archive, import/export conversation history |\n| **Desktop App** | 15+ feature pages with real-time streaming, typewriter animation, and context menus |\n\n---\n\n## Quick Start\n\n### Prerequisites\n\n- **Python 3.11+** β to run MiQi backend\n- **Node.js 20+** β to run Electron frontend\n- **uv** β Python package manager (recommended)\n\n### Installation\n\n```bash\n# 1. Clone the repository\ngit clone http://git.miqroera.com/intership/miqi-desktop.git\ncd miqi-desktop\n\n# 2. Install Python dependencies\nuv sync\n\n# 3. Install frontend dependencies\ncd apps/desktop\nnpm install\n```\n\n### Development Mode\n\n```bash\n# Start Electron dev server with hot-reload\ncd apps/desktop\nnpm run dev\n```\n\n### Production Build\n\n**One-step build** (recommended):\n\n```bash\ncd apps/desktop\nnpm run build:all # Python backend β Frontend compile β Electron package\n```\n\n**Step-by-step build**:\n\n```bash\ncd apps/desktop\n\n# 1. Build Python backend (generates dist/miqi-bridge.exe)\nnpm run build:bridge\n\n# 2. Compile frontend\nnpm run build\n\n# 3. Package as desktop application\nnpx electron-builder --win --publish never\n```\n\nThe packaged `miqi-bridge.exe` is a self-contained binary (PyInstaller onefile) that includes Python and all dependencies β no system Python installation required on the target machine. It also supports a `--check` flag for environment validation:\n\n```bash\nmiqi-bridge.exe --check\n# Output: {\"ok\": true, \"python_version\": \"3.12.10\", \"issues\": []}\n```\n\n---\n\n## Architecture\n\n```\nβββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ\nβ MiQi Desktop App β\nβββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€\nβ Electron Frontend β\nβ βββ React 19 + TypeScript β\nβ βββ Tailwind CSS 4 + shadcn/ui β\nβ βββ 15+ Feature Pages (Chat, Agents, Skills, MCPs, ...) β\nβββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€\nβ Bridge (IPC Communication) β\nβ βββ stdin/stdout JSON-line protocol β\nβ βββ State synchronization + Log forwarding β\nβ βββ BridgeRuntimeLoop (persistent asyncio event loop) β\nβββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€\nβ AppServer (Typed Protocol Layer) β\nβ βββ ProtocolRegistry (typed method specs) β\nβ βββ Typed Envelopes (Pydantic v2) β\nβ βββ JSON Schema Draft 2020-12 Catalog β\nβ βββ Handler Typed Validation β\nβββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€\nβ MiQi Runtime Engine β\nβ βββ RuntimeSession / TaskRunner / TurnRunner β\nβ βββ HistoryRuntime + LedgerRuntime (SQLite persistence) β\nβ βββ ContextRuntime (compaction, token budgeting) β\nβ βββ ThreadRuntime (fork, rollback, import/export) β\nβ βββ ReplayRuntime (deterministic replay inspection) β\nβββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€\nβ Execution & Sandbox β\nβ βββ ToolOrchestrator (approval β sandbox β execute) β\nβ βββ PermissionEngine + ApprovalPolicy + HookRuntime β\nβ βββ bwrap Sandbox (LANDLOCK, streaming, cancellation) β\nβ βββ Workbench Process Runtime (command/exec, process/*) β\nβββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€\nβ Tools & Integrations β\nβ βββ Built-in Tools (filesystem, shell, web, papers, ...) β\nβ βββ MCP Client (external tool servers) β\nβ βββ Plugin Manager + Skill Loader β\nβ βββ Office Document Tools (docx, pptx, xlsx) β\nβββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ\n```\n\n1. Launch the application\n2. Go through the setup wizard:\n - **Environment Check** β validates Python and dependencies (bundled exe auto-detects; dev mode checks system Python)\n - **WSL2 Setup** β (Windows only) auto-detects and installs WSL2 for sandbox support\n - **LLM Provider** β configure API keys and default model\n3. Start chatting with the AI agent\n### Protocol Method Families\n\n| Family | Scope | Methods |\n|--------|-------|---------|\n| `turn/*` | Turn | start, interrupt, steer |\n| `thread/*` | Thread | list, get, rollback, fork, delete, compact/start, inject_items |\n| `fs/*` | Filesystem | readFile, writeFile, createDirectory, getMetadata, readDirectory, remove, copy, watch, unwatch |\n| `fuzzyFileSearch/*` | Filesystem | sessionStart, sessionUpdate, sessionStop |\n| `command/exec` | Process | exec, exec/write, exec/resize, exec/terminate |\n| `process/*` | Process | spawn, writeStdin, resizePty, kill, list, get, snapshot |\n| `replay.*` | Debug | turns, timeline, messages |\n| `config/*` | Session | get, batchWrite |\n| `model/*` | Session | list, get |\n| `feature/*` | Session | list, set |\n| `permission/*` | Session | listProfiles, getProfile |\n| `plugin/*` | Session | list, install, uninstall, enable, disable, configure |\n| `skills/*` | Session | list, get, create, upload, delete, setExtraRoots |\n| `mcp/*` | Session | listServers, getServer, status |\n| `agent/*` | Session | list, get, spawn, kill |\n| `protocol/*` | Connection | catalog, method_names, schema |\n\n---\n\n## Configuration\n\nThe application configuration file is located at `~/.miqi/config.json`:\n\n```json\n{\n \"providers\": {\n \"openai\": { \"apiKey\": \"sk-...\" },\n \"anthropic\": { \"apiKey\": \"sk-ant-...\" }\n },\n \"agents\": {\n \"defaults\": {\n \"model\": \"claude-sonnet-4-6\",\n \"temperature\": 0.1,\n \"maxToolIterations\": 100\n }\n },\n \"tools\": {\n \"restrictToWorkspace\": true\n }\n}\n```\n\n### Environment Variables\n\n| Variable | Description |\n|---|---|\n| `MIQI_PYTHON_PATH` | Custom Python interpreter path |\n| `MIQI_AGENTS__DEFAULTS__MODEL` | Override default model |\n\n---\n\n## Development Guide\n\n### Project Structure\n\n```\nmiqi-desktop/\nβββ miqi/ # Python backend\nβ βββ runtime/ # Runtime engine (AppServer, Session, Turn, Thread, Replay, Agent, MCP, ...)\nβ βββ agent/ # Agent logic, tools, memory, trace, context compression, smart routing\nβ βββ bridge/ # Electron bridge service (IPC protocol)\nβ βββ bus/ # Internal message bus (async in/out queues)\nβ βββ execution/ # Tool orchestrator, permissions, approval, hooks, sandbox policy\nβ βββ providers/ # LLM provider implementations + resilience\nβ βββ protocol/ # Typed commands, events, permissions (runtime-frontend protocol)\nβ βββ channels/ # Chat channel adapters (Feishu, Slack, Discord, Telegram, ...)\nβ βββ sandbox/ # bwrap sandbox manager\nβ βββ skills/ # Built-in skills (cron, paper-research, feishu-report, ...)\nβ βββ session/ # Session management (Manager, SQLite store)\nβ βββ config/ # Configuration loader and schema\nβ βββ cli/ # CLI commands (agent, gateway, trace, config)\nβ βββ cron/ # Cron scheduler service\nβ βββ context/ # Context fragments, thread store\nβ βββ heartbeat/ # Heartbeat service\nβ βββ plan/ # Plan tracker and tool\nβ βββ documents/ # Office document tools (docx, pptx, xlsx)\nβ βββ observability/ # OpenTelemetry integration\nβ βββ server/ # Server assets and configuration\nβ βββ templates/ # Templates\nβ βββ tui/ # Terminal UI (Textual-based)\nβ βββ utils/ # Utility functions\nβββ apps/\nβ βββ desktop/ # Electron frontend\nβ βββ src/main/ # Main process (BridgeManager, IPC handlers)\nβ βββ src/renderer/ # Renderer (React pages and components)\nβ βββ src/preload/ # Preload scripts (contextBridge API)\nβββ tests/ # Test suite (~150+ test files)\nβ βββ runtime/ # Runtime unit and integration tests (~70+ files)\nβ βββ bridge/ # Bridge protocol and audit tests (~20+ files)\nβ βββ execution/ # Sandbox, permissions, orchestration tests\nβ βββ providers/ # LLM provider tests\nβ βββ protocol/ # Protocol commands/events/permissions tests\nβ βββ agent/tools/ # Tool-level tests\nβββ docs/ # Documentation (MkDocs)\nβββ plan/ # Implementation plans (not in VCS deliverables)\nβββ scripts/ # Build and utility scripts\n```\n\n### Code Standards\n\n- **Python**: Ruff for linting (line-length 100)\n- **TypeScript**: ESLint for linting\n- **Commit Messages**: Conventional Commits format\n\n### Testing\n\n```bash\n# Python backend tests (~1800+ tests)\nuv run pytest\n\n# Skip sandbox/subprocess tests for quick feedback\nuv run pytest -m \"not sandbox and not subprocess\"\n\n# Frontend tests\ncd apps/desktop\nnpm run test\n```\n\n---\n\n## Documentation\n\n- [Getting Started](docs/getting-started.md)\n- [Architecture](docs/architecture.md)\n- [Configuration](docs/configuration.md)\n- [MCP Integration](docs/mcp-integration.md)\n- [Developer Guide](docs/developer-guide.md)\n- [Internal Alpha Smoke](docs/internal-alpha-smoke.md)\n\n---\n\n## License\n\n[MIT License](LICENSE)\n\n---\n\n## Contributing\n\nContributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details.\ntest\n"}, "530b35cde35ab21d314e05287a1d57dcc56ea634": {"t": 1785771667.168424, "n": 12752, "h": "35fe7564f1abe700", "c": "# MiQi\n\n\n πββ¬πͺΆ A lightweight, extensible personal AI agent framework with a modern desktop interface\n
\n\n\n \n \n \n \n
\n\n---\n\n## Overview\n\nMiQi Desktop is an Electron-based desktop application that provides a modern graphical interface for the MiQi AI agent. It combines powerful AI agent capabilities with an intuitive user interface, supporting chat interaction, memory management, task scheduling, and more.\n\n\n### Core Positioning\n\n- π― **Personal AI Agent** β not just a chatbot: persistent memory, learned skills, file operations, and scheduled tasks\n- π§ **Highly Extensible** β MCP protocol for external tools, custom skills, and pluggable LLM providers\n- π₯οΈ **Native Desktop Experience** β Electron with system-level integration (WSL2 sandbox, filesystem operations)\n- π **Local-First** β all data stored locally; non-destructive file editing with versioned snapshots\n- π **Typed Application Protocol** β typed AppServer with JSON Schema catalog, method stability tracking, and handler-boundary validation\n\n### Tech Stack\n\n| Layer | Technology | Version |\n|-------|-----------|---------|\n| Desktop Framework | Electron | 35.2 |\n| Frontend UI | React + TypeScript | 19.1 / 5.8 |\n| CSS | Tailwind CSS 4 | 4.x |\n| Component Library | Radix UI + Lucide Icons | β |\n| Python Runtime | Python (asyncio) | 3.11+ |\n| Data Validation | Pydantic v2 | 2.12+ |\n| CLI Framework | Typer | 0.20+ |\n| Build (Desktop) | electron-vite + electron-builder | 3.1 / 26.0 |\n| Build (Python) | PyInstaller + Hatchling | 6.20+ |\n\n---\n\n## Key Features\n\n| Feature | Description |\n|---|---|\n| **Smart Chat** | Natural language conversation with streaming responses and tool-call progress |\n| **Multi-Provider** | OpenAI, Anthropic, Gemini, OpenRouter, DeepSeek, and more β with provider resilience |\n| **Typed Protocol** | Typed AppServer with method specs, JSON Schema catalog, and handler-boundary validation |\n| **Memory System** | Long-term memory snapshots, self-improvement lessons, and cross-session recall |\n| **Task Scheduler** | Cron-based scheduled tasks with timezone support |\n| **Skill System** | Create, upload, and manage agent skills; SkillHub registry integration |\n| **Plugin Ecology** | MCP servers, plugins, and marketplace with deterministic catalog |\n| **Sandbox Execution** | bwrap-based sandbox with LANDLOCK filesystem rules, streaming I/O, and process lifecycle |\n| **File Management** | Workspace FS with watch, fuzzy search, snapshot/versioning, and non-destructive editing |\n| **Replay & Debug** | Deterministic replay of turns, timeline, and messages for inspection |\n| **Session Management** | Browse, search, archive, import/export conversation history |\n| **Desktop App** | 15+ feature pages with real-time streaming, typewriter animation, and context menus |\n\n---\n\n## Quick Start\n\n### Prerequisites\n\n- **Python 3.11+** β to run MiQi backend\n- **Node.js 20+** β to run Electron frontend\n- **uv** β Python package manager (recommended)\n\n### Installation\n\n```bash\n# 1. Clone the repository\ngit clone http://git.miqroera.com/intership/miqi-desktop.git\ncd miqi-desktop\n\n# 2. Install Python dependencies\nuv sync\n\n# 3. Install frontend dependencies\ncd apps/desktop\nnpm install\n```\n\n### Development Mode\n\n```bash\n# Start Electron dev server with hot-reload\ncd apps/desktop\nnpm run dev\n```\n\n### Production Build\n\n**One-step build** (recommended):\n\n```bash\ncd apps/desktop\nnpm run build:all # Python backend β Frontend compile β Electron package\n```\n\n**Step-by-step build**:\n\n```bash\ncd apps/desktop\n\n# 1. Build Python backend (generates dist/miqi-bridge.exe)\nnpm run build:bridge\n\n# 2. Compile frontend\nnpm run build\n\n# 3. Package as desktop application\nnpx electron-builder --win --publish never\n```\n\nThe packaged `miqi-bridge.exe` is a self-contained binary (PyInstaller onefile) that includes Python and all dependencies β no system Python installation required on the target machine. It also supports a `--check` flag for environment validation:\n\n```bash\nmiqi-bridge.exe --check\n# Output: {\"ok\": true, \"python_version\": \"3.12.10\", \"issues\": []}\n```\n\n---\n\n## Architecture\n\n```\nβββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ\nβ MiQi Desktop App β\nβββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€\nβ Electron Frontend β\nβ βββ React 19 + TypeScript β\nβ βββ Tailwind CSS 4 + shadcn/ui β\nβ βββ 15+ Feature Pages (Chat, Agents, Skills, MCPs, ...) β\nβββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€\nβ Bridge (IPC Communication) β\nβ βββ stdin/stdout JSON-line protocol β\nβ βββ State synchronization + Log forwarding β\nβ βββ BridgeRuntimeLoop (persistent asyncio event loop) β\nβββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€\nβ AppServer (Typed Protocol Layer) β\nβ βββ ProtocolRegistry (typed method specs) β\nβ βββ Typed Envelopes (Pydantic v2) β\nβ βββ JSON Schema Draft 2020-12 Catalog β\nβ βββ Handler Typed Validation β\nβββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€\nβ MiQi Runtime Engine β\nβ βββ RuntimeSession / TaskRunner / TurnRunner β\nβ βββ HistoryRuntime + LedgerRuntime (SQLite persistence) β\nβ βββ ContextRuntime (compaction, token budgeting) β\nβ βββ ThreadRuntime (fork, rollback, import/export) β\nβ βββ ReplayRuntime (deterministic replay inspection) β\nβββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€\nβ Execution & Sandbox β\nβ βββ ToolOrchestrator (approval β sandbox β execute) β\nβ βββ PermissionEngine + ApprovalPolicy + HookRuntime β\nβ βββ bwrap Sandbox (LANDLOCK, streaming, cancellation) β\nβ βββ Workbench Process Runtime (command/exec, process/*) β\nβββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€\nβ Tools & Integrations β\nβ βββ Built-in Tools (filesystem, shell, web, papers, ...) β\nβ βββ MCP Client (external tool servers) β\nβ βββ Plugin Manager + Skill Loader β\nβ βββ Office Document Tools (docx, pptx, xlsx) β\nβββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ\n```\n\n1. Launch the application\n2. Go through the setup wizard:\n - **Environment Check** β validates Python and dependencies (bundled exe auto-detects; dev mode checks system Python)\n - **WSL2 Setup** β (Windows only) auto-detects and installs WSL2 for sandbox support\n - **LLM Provider** β configure API keys and default model\n3. Start chatting with the AI agent\n### Protocol Method Families\n\n| Family | Scope | Methods |\n|--------|-------|---------|\n| `turn/*` | Turn | start, interrupt, steer |\n| `thread/*` | Thread | list, get, rollback, fork, delete, compact/start, inject_items |\n| `fs/*` | Filesystem | readFile, writeFile, createDirectory, getMetadata, readDirectory, remove, copy, watch, unwatch |\n| `fuzzyFileSearch/*` | Filesystem | sessionStart, sessionUpdate, sessionStop |\n| `command/exec` | Process | exec, exec/write, exec/resize, exec/terminate |\n| `process/*` | Process | spawn, writeStdin, resizePty, kill, list, get, snapshot |\n| `replay.*` | Debug | turns, timeline, messages |\n| `config/*` | Session | get, batchWrite |\n| `model/*` | Session | list, get |\n| `feature/*` | Session | list, set |\n| `permission/*` | Session | listProfiles, getProfile |\n| `plugin/*` | Session | list, install, uninstall, enable, disable, configure |\n| `skills/*` | Session | list, get, create, upload, delete, setExtraRoots |\n| `mcp/*` | Session | listServers, getServer, status |\n| `agent/*` | Session | list, get, spawn, kill |\n| `protocol/*` | Connection | catalog, method_names, schema |\n\n---\n\n## Configuration\n\nThe application configuration file is located at `~/.miqi/config.json`:\n\n```json\n{\n \"providers\": {\n \"openai\": { \"apiKey\": \"sk-...\" },\n \"anthropic\": { \"apiKey\": \"sk-ant-...\" }\n },\n \"agents\": {\n \"defaults\": {\n \"model\": \"claude-sonnet-4-6\",\n \"temperature\": 0.1,\n \"maxToolIterations\": 100\n }\n },\n \"tools\": {\n \"restrictToWorkspace\": true\n }\n}\n```\n\n### Environment Variables\n\n| Variable | Description |\n|---|---|\n| `MIQI_PYTHON_PATH` | Custom Python interpreter path |\n| `MIQI_AGENTS__DEFAULTS__MODEL` | Override default model |\n\n---\n\n## Development Guide\n\n### Project Structure\n\n```\nmiqi-desktop/\nβββ miqi/ # Python backend\nβ βββ runtime/ # Runtime engine (AppServer, Session, Turn, Thread, Replay, Agent, MCP, ...)\nβ βββ agent/ # Agent logic, tools, memory, trace, context compression, smart routing\nβ βββ bridge/ # Electron bridge service (IPC protocol)\nβ βββ bus/ # Internal message bus (async in/out queues)\nβ βββ execution/ # Tool orchestrator, permissions, approval, hooks, sandbox policy\nβ βββ providers/ # LLM provider implementations + resilience\nβ βββ protocol/ # Typed commands, events, permissions (runtime-frontend protocol)\nβ βββ channels/ # Chat channel adapters (Feishu, Slack, Discord, Telegram, ...)\nβ βββ sandbox/ # bwrap sandbox manager\nβ βββ skills/ # Built-in skills (cron, paper-research, feishu-report, ...)\nβ βββ session/ # Session management (Manager, SQLite store)\nβ βββ config/ # Configuration loader and schema\nβ βββ cli/ # CLI commands (agent, gateway, trace, config)\nβ βββ cron/ # Cron scheduler service\nβ βββ context/ # Context fragments, thread store\nβ βββ heartbeat/ # Heartbeat service\nβ βββ plan/ # Plan tracker and tool\nβ βββ documents/ # Office document tools (docx, pptx, xlsx)\nβ βββ observability/ # OpenTelemetry integration\nβ βββ server/ # Server assets and configuration\nβ βββ templates/ # Templates\nβ βββ tui/ # Terminal UI (Textual-based)\nβ βββ utils/ # Utility functions\nβββ apps/\nβ βββ desktop/ # Electron frontend\nβ βββ src/main/ # Main process (BridgeManager, IPC handlers)\nβ βββ src/renderer/ # Renderer (React pages and components)\nβ βββ src/preload/ # Preload scripts (contextBridge API)\nβββ tests/ # Test suite (~150+ test files)\nβ βββ runtime/ # Runtime unit and integration tests (~70+ files)\nβ βββ bridge/ # Bridge protocol and audit tests (~20+ files)\nβ βββ execution/ # Sandbox, permissions, orchestration tests\nβ βββ providers/ # LLM provider tests\nβ βββ protocol/ # Protocol commands/events/permissions tests\nβ βββ agent/tools/ # Tool-level tests\nβββ docs/ # Documentation (MkDocs)\nβββ plan/ # Implementation plans (not in VCS deliverables)\nβββ scripts/ # Build and utility scripts\n```\n\n### Code Standards\n\n- **Python**: Ruff for linting (line-length 100)\n- **TypeScript**: ESLint for linting\n- **Commit Messages**: Conventional Commits format\n\n### Testing\n\n```bash\n# Python backend tests (~1800+ tests)\nuv run pytest\n\n# Skip sandbox/subprocess tests for quick feedback\nuv run pytest -m \"not sandbox and not subprocess\"\n\n# Frontend tests\ncd apps/desktop\nnpm run test\n```\n\n---\n\n## Documentation\n\n- [Getting Started](docs/getting-started.md)\n- [Architecture](docs/architecture.md)\n- [Configuration](docs/configuration.md)\n- [MCP Integration](docs/mcp-integration.md)\n- [Developer Guide](docs/developer-guide.md)\n- [Internal Alpha Smoke](docs/internal-alpha-smoke.md)\n\n---\n\n## License\n\n[MIT License](LICENSE)\n\n---\n\n## Contributing\n\nContributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details.\n"}, "97781a2eb2cd78c191220f7275f4465e107fc5ec": {"t": 1785771670.0329354, "n": 7317, "h": "5df9d1e2f0ff88e6", "c": "# MiQi Desktop\n\n\n πββ¬πͺΆ A lightweight, extensible personal AI agent with a modern desktop interface\n
\n\n\n \n \n \n \n
\n\n---\n\n## Overview\n\nMiQi Desktop is an Electron-based desktop application that provides a modern graphical interface for the MiQi AI agent. It combines powerful AI agent capabilities with an intuitive user interface, supporting chat interaction, memory management, task scheduling, and more.\n\n## Key Features\n\n| Feature | Description |\n|---|---|\n| **Smart Chat** | Natural language conversation with AI agent |\n| **Multi-provider Support** | Supports OpenAI, Anthropic, Gemini, OpenRouter, and more LLM providers |\n| **Multi-channel** | Connect via Feishu, WeChat, DingTalk and more message channels |\n| **Memory System** | Manage long-term memory snapshots and self-improvement lessons |\n| **Session Management** | Browse, search, and compact conversation history |\n| **Task Scheduler** | Create and manage scheduled tasks (Cron support) |\n| **Skill System** | Configure and enable various agent skills |\n| **Sandbox Isolation** | Per-session bwrap sandbox on WSL2 for safe code execution |\n| **File Management** | Workspace file system operations |\n| **Real-time Logs** | Monitor agent activity and debug information |\n\n---\n\n## Quick Start\n\n### Prerequisites\n\n- **Python 3.11+** - Required to run MiQi backend\n- **Node.js 20+** - Required to run Electron frontend\n- **uv** - Python package manager (recommended)\n\n### Installation\n\n```bash\n# 1. Clone the repository\ngit clone http://git.miqroera.com/intership/miqi-desktop.git\ncd miqi-desktop\n\n# 2. Install Python dependencies\nuv sync\n\n# 3. Install frontend dependencies\ncd apps/desktop\nnpm install\n```\n\n### Development Mode\n\n```bash\n# Start Electron dev server with hot-reload\ncd apps/desktop\nnpm run dev\n```\n\n### Production Build\n\n**One-step build** (recommended):\n\n```bash\ncd apps/desktop\nnpm run build:all # Python backend β Frontend compile β Electron package\n```\n\n**Step-by-step build**:\n\n```bash\ncd apps/desktop\n\n# 1. Build Python backend (generates dist/miqi-bridge.exe)\nnpm run build:bridge\n\n# 2. Compile frontend\nnpm run build\n\n# 3. Package as desktop application\nnpx electron-builder --win --publish never\n```\n\nThe packaged `miqi-bridge.exe` is a self-contained binary (PyInstaller onefile) that includes Python and all dependencies β no system Python installation required on the target machine. It also supports a `--check` flag for environment validation:\n\n```bash\nmiqi-bridge.exe --check\n# Output: {\"ok\": true, \"python_version\": \"3.12.10\", \"issues\": []}\n```\n\n---\n\n## Usage Guide\n\n### First Run\n\n1. Launch the application\n2. Go through the setup wizard:\n - **Environment Check** β validates Python and dependencies (bundled exe auto-detects; dev mode checks system Python)\n - **WSL2 Setup** β (Windows only) auto-detects and installs WSL2 for sandbox support\n - **LLM Provider** β configure API keys and default model\n3. Start chatting with the AI agent\n\n### Core Features\n\n**Chat Interface**\n- Markdown format support\n- Real-time tool call progress\n- Code syntax highlighting\n\n**Provider Management**\n- Add/edit LLM provider configurations\n- Test connection status\n- Switch default models\n\n**Memory Management**\n- View long-term memory snapshots\n- Manage self-improvement lessons\n- Import/export memory data\n\n**Task Scheduler**\n- Create scheduled tasks (Cron expressions supported)\n- Enable/disable tasks\n- Manually trigger task execution\n\n---\n\n## Configuration\n\nThe application configuration file is located at `~/.miqi/config.json` and contains the following main configuration options:\n\n```json\n{\n \"providers\": {\n \"openai\": { \"apiKey\": \"sk-...\" },\n \"anthropic\": { \"apiKey\": \"sk-ant-...\" }\n },\n \"agents\": {\n \"defaults\": {\n \"model\": \"gpt-4o\",\n \"temperature\": 0.1,\n \"maxToolIterations\": 50\n }\n },\n \"tools\": {\n \"restrictToWorkspace\": true\n }\n}\n```\n\n### Environment Variables\n\n| Variable | Description |\n|---|---|\n| `MIQI_PYTHON_PATH` | Custom Python interpreter path |\n| `MIQI_AGENTS__DEFAULTS__MODEL` | Override default model |\n\n---\n\n## Architecture\n\n```\nβββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ\nβ MiQi Desktop App β\nβββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€\nβ Electron Frontend β\nβ βββ React + TypeScript β\nβ βββ Tailwind CSS β\nβ βββ Radix UI Components β\nβββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€\nβ Bridge (IPC Communication) β\nβ βββ stdout/stderr JSON protocol β\nβ βββ State synchronization β\nβ βββ Log forwarding β\nβββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€\nβ MiQi Python Runtime β\nβ βββ AgentLoop (Core agent engine) β\nβ βββ Memory System β\nβ βββ Tool Registry β\nβ βββ Provider Interface β\nβ βββ Channel Bus (Feishu / WeChat / DingTalk) β\nβββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€\nβ Sandbox Layer (WSL2 + bwrap) β\nβ βββ Per-session isolation β\nβ βββ Filesystem sandboxing β\nβ βββ Safe code execution β\nβββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ\n```\n\n---\n\n## Development Guide\n\n### Project Structure\n\n```\nmiqi-desktop/\nβββ miqi/ # Python backend code\nβ βββ agent/ # Core agent logic & tool registry\nβ βββ bridge/ # Bridge service for Electron communication\nβ βββ providers/ # LLM provider implementations\nβ βββ channels/ # Message channel adapters (Feishu/WeChat/DingTalk)\nβ βββ sandbox/ # bwrap sandbox manager (WSL2)\nβ βββ ...\nβββ apps/\nβ βββ desktop/ # Electron frontend application\nβ βββ src/\nβ β βββ main/ # Main process (IPC handlers, BridgeManager)\nβ β βββ renderer/ # Renderer process (React UI)\nβ β βββ preload/ # Preload scripts (contextBridge)\nβ βββ electron-builder.yml\nβββ ...\n```\n\n### Code Standards\n\n- **Python**: Ruff for linting\n- **TypeScript**: ESLint for linting\n- **Commit Messages**: Conventional Commits format\n\n### Testing\n\n```bash\n# Python backend tests\nuv run pytest\n\n# Frontend tests\ncd apps/desktop\nnpm run test\n```\n\n---\n\n## License\n\n[MIT License](LICENSE)\n\n---\n\n## Contributing\n\nContributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details.\n"}, "648d711b0acc0160cdd515265c3d7ef99f3166d7": {"t": 1785771672.2682447, "n": 12796, "h": "54798a9c2dc6b31a", "c": "# MiQi\n\n\n πββ¬πͺΆ A lightweight, extensible personal AI agent framework with a modern desktop interface\n
\n\n\n \n \n \n \n
\n\n---\n\n## Overview\n\nMiQi is a personal AI agent framework that combines a powerful **Python runtime engine** with an **Electron desktop application**. It provides a typed application server protocol, request validation, multi-provider LLM support, sandboxed command execution, and a plugin/skills ecology β all with a local-first, privacy-respecting architecture.\n\n### Core Positioning\n\n- π― **Personal AI Agent** β not just a chatbot: persistent memory, learned skills, file operations, and scheduled tasks\n- π§ **Highly Extensible** β MCP protocol for external tools, custom skills, and pluggable LLM providers\n- π₯οΈ **Native Desktop Experience** β Electron with system-level integration (WSL2 sandbox, filesystem operations)\n- π **Local-First** β all data stored locally; non-destructive file editing with versioned snapshots\n- π **Typed Application Protocol** β typed AppServer with JSON Schema catalog, method stability tracking, and handler-boundary validation\n\n### Tech Stack\n\n| Layer | Technology | Version |\n|-------|-----------|---------|\n| Desktop Framework | Electron | 35.2 |\n| Frontend UI | React + TypeScript | 19.1 / 5.8 |\n| CSS | Tailwind CSS 4 | 4.x |\n| Component Library | Radix UI + Lucide Icons | β |\n| Python Runtime | Python (asyncio) | 3.11+ |\n| Data Validation | Pydantic v2 | 2.12+ |\n| CLI Framework | Typer | 0.20+ |\n| Build (Desktop) | electron-vite + electron-builder | 3.1 / 26.0 |\n| Build (Python) | PyInstaller + Hatchling | 6.20+ |\n\n---\n\n## Key Features\n\n| Feature | Description |\n|---|---|\n| **Smart Chat** | Natural language conversation with streaming responses and tool-call progress |\n| **Multi-Provider** | OpenAI, Anthropic, Gemini, OpenRouter, DeepSeek, and more β with provider resilience |\n| **Typed Protocol** | Typed AppServer with method specs, JSON Schema catalog, and handler-boundary validation |\n| **Memory System** | Long-term memory snapshots, self-improvement lessons, and cross-session recall |\n| **Task Scheduler** | Cron-based scheduled tasks with timezone support |\n| **Skill System** | Create, upload, and manage agent skills; SkillHub registry integration |\n| **Plugin Ecology** | MCP servers, plugins, and marketplace with deterministic catalog |\n| **Sandbox Execution** | bwrap-based sandbox with LANDLOCK filesystem rules, streaming I/O, and process lifecycle |\n| **File Management** | Workspace FS with watch, fuzzy search, snapshot/versioning, and non-destructive editing |\n| **Replay & Debug** | Deterministic replay of turns, timeline, and messages for inspection |\n| **Session Management** | Browse, search, archive, import/export conversation history |\n| **Desktop App** | 15+ feature pages with real-time streaming, typewriter animation, and context menus |\n\n---\n\n## Quick Start\n\n### Prerequisites\n\n- **Python 3.11+** β to run MiQi backend\n- **Node.js 20+** β to run Electron frontend\n- **uv** β Python package manager (recommended)\n\n### Installation\n\n```bash\n# 1. Clone the repository\ngit clone http://git.miqroera.com/intership/miqi-desktop.git\ncd miqi-desktop\n\n# 2. Install Python dependencies\nuv sync\n\n# 3. Install frontend dependencies\ncd apps/desktop\nnpm install\n```\n\n### Development Mode\n\n```bash\n# Start Electron dev server with hot-reload\ncd apps/desktop\nnpm run dev\n```\n\n### Production Build\n\n**One-step build** (recommended):\n\n```bash\ncd apps/desktop\nnpm run build:all # Python backend β Frontend compile β Electron package\n```\n\n**Step-by-step build**:\n\n```bash\ncd apps/desktop\n\n# 1. Build Python backend (generates dist/miqi-bridge.exe)\nnpm run build:bridge\n\n# 2. Compile frontend\nnpm run build\n\n# 3. Package as desktop application\nnpx electron-builder --win --publish never\n```\n\nThe packaged `miqi-bridge.exe` is a self-contained binary (PyInstaller onefile) that includes Python and all dependencies β no system Python installation required on the target machine. It also supports a `--check` flag for environment validation:\n\n```bash\nmiqi-bridge.exe --check\n# Output: {\"ok\": true, \"python_version\": \"3.12.10\", \"issues\": []}\n```\n\n---\n\n## Architecture\n\n```\nβββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ\nβ MiQi Desktop App β\nβββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€\nβ Electron Frontend β\nβ βββ React 19 + TypeScript β\nβ βββ Tailwind CSS 4 + shadcn/ui β\nβ βββ 15+ Feature Pages (Chat, Agents, Skills, MCPs, ...) β\nβββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€\nβ Bridge (IPC Communication) β\nβ βββ stdin/stdout JSON-line protocol β\nβ βββ State synchronization + Log forwarding β\nβ βββ BridgeRuntimeLoop (persistent asyncio event loop) β\nβββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€\nβ AppServer (Typed Protocol Layer) β\nβ βββ ProtocolRegistry (typed method specs) β\nβ βββ Typed Envelopes (Pydantic v2) β\nβ βββ JSON Schema Draft 2020-12 Catalog β\nβ βββ Handler Typed Validation β\nβββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€\nβ MiQi Runtime Engine β\nβ βββ RuntimeSession / TaskRunner / TurnRunner β\nβ βββ HistoryRuntime + LedgerRuntime (SQLite persistence) β\nβ βββ ContextRuntime (compaction, token budgeting) β\nβ βββ ThreadRuntime (fork, rollback, import/export) β\nβ βββ ReplayRuntime (deterministic replay inspection) β\nβββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€\nβ Execution & Sandbox β\nβ βββ ToolOrchestrator (approval β sandbox β execute) β\nβ βββ PermissionEngine + ApprovalPolicy + HookRuntime β\nβ βββ bwrap Sandbox (LANDLOCK, streaming, cancellation) β\nβ βββ Workbench Process Runtime (command/exec, process/*) β\nβββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€\nβ Tools & Integrations β\nβ βββ Built-in Tools (filesystem, shell, web, papers, ...) β\nβ βββ MCP Client (external tool servers) β\nβ βββ Plugin Manager + Skill Loader β\nβ βββ Office Document Tools (docx, pptx, xlsx) β\nβββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ\n```\n\n1. Launch the application\n2. Go through the setup wizard:\n - **Environment Check** β validates Python and dependencies (bundled exe auto-detects; dev mode checks system Python)\n - **WSL2 Setup** β (Windows only) auto-detects and installs WSL2 for sandbox support\n - **LLM Provider** β configure API keys and default model\n3. Start chatting with the AI agent\n### Protocol Method Families\n\n| Family | Scope | Methods |\n|--------|-------|---------|\n| `turn/*` | Turn | start, interrupt, steer |\n| `thread/*` | Thread | list, get, rollback, fork, delete, compact/start, inject_items |\n| `fs/*` | Filesystem | readFile, writeFile, createDirectory, getMetadata, readDirectory, remove, copy, watch, unwatch |\n| `fuzzyFileSearch/*` | Filesystem | sessionStart, sessionUpdate, sessionStop |\n| `command/exec` | Process | exec, exec/write, exec/resize, exec/terminate |\n| `process/*` | Process | spawn, writeStdin, resizePty, kill, list, get, snapshot |\n| `replay.*` | Debug | turns, timeline, messages |\n| `config/*` | Session | get, batchWrite |\n| `model/*` | Session | list, get |\n| `feature/*` | Session | list, set |\n| `permission/*` | Session | listProfiles, getProfile |\n| `plugin/*` | Session | list, install, uninstall, enable, disable, configure |\n| `skills/*` | Session | list, get, create, upload, delete, setExtraRoots |\n| `mcp/*` | Session | listServers, getServer, status |\n| `agent/*` | Session | list, get, spawn, kill |\n| `protocol/*` | Connection | catalog, method_names, schema |\n\n---\n\n## Configuration\n\nThe application configuration file is located at `~/.miqi/config.json`:\n\n```json\n{\n \"providers\": {\n \"openai\": { \"apiKey\": \"sk-...\" },\n \"anthropic\": { \"apiKey\": \"sk-ant-...\" }\n },\n \"agents\": {\n \"defaults\": {\n \"model\": \"claude-sonnet-4-6\",\n \"temperature\": 0.1,\n \"maxToolIterations\": 100\n }\n },\n \"tools\": {\n \"restrictToWorkspace\": true\n }\n}\n```\n\n### Environment Variables\n\n| Variable | Description |\n|---|---|\n| `MIQI_PYTHON_PATH` | Custom Python interpreter path |\n| `MIQI_AGENTS__DEFAULTS__MODEL` | Override default model |\n\n---\n\n## Development Guide\n\n### Project Structure\n\n```\nmiqi-desktop/\nβββ miqi/ # Python backend\nβ βββ runtime/ # Runtime engine (AppServer, Session, Turn, Thread, Replay, Agent, MCP, ...)\nβ βββ agent/ # Agent logic, tools, memory, trace, context compression, smart routing\nβ βββ bridge/ # Electron bridge service (IPC protocol)\nβ βββ bus/ # Internal message bus (async in/out queues)\nβ βββ execution/ # Tool orchestrator, permissions, approval, hooks, sandbox policy\nβ βββ providers/ # LLM provider implementations + resilience\nβ βββ protocol/ # Typed commands, events, permissions (runtime-frontend protocol)\nβ βββ channels/ # Chat channel adapters (Feishu, Slack, Discord, Telegram, ...)\nβ βββ sandbox/ # bwrap sandbox manager\nβ βββ skills/ # Built-in skills (cron, paper-research, feishu-report, ...)\nβ βββ session/ # Session management (Manager, SQLite store)\nβ βββ config/ # Configuration loader and schema\nβ βββ cli/ # CLI commands (agent, gateway, trace, config)\nβ βββ cron/ # Cron scheduler service\nβ βββ context/ # Context fragments, thread store\nβ βββ heartbeat/ # Heartbeat service\nβ βββ plan/ # Plan tracker and tool\nβ βββ documents/ # Office document tools (docx, pptx, xlsx)\nβ βββ observability/ # OpenTelemetry integration\nβ βββ server/ # Server assets and configuration\nβ βββ templates/ # Templates\nβ βββ tui/ # Terminal UI (Textual-based)\nβ βββ utils/ # Utility functions\nβββ apps/\nβ βββ desktop/ # Electron frontend\nβ βββ src/main/ # Main process (BridgeManager, IPC handlers)\nβ βββ src/renderer/ # Renderer (React pages and components)\nβ βββ src/preload/ # Preload scripts (contextBridge API)\nβββ tests/ # Test suite (~150+ test files)\nβ βββ runtime/ # Runtime unit and integration tests (~70+ files)\nβ βββ bridge/ # Bridge protocol and audit tests (~20+ files)\nβ βββ execution/ # Sandbox, permissions, orchestration tests\nβ βββ providers/ # LLM provider tests\nβ βββ protocol/ # Protocol commands/events/permissions tests\nβ βββ agent/tools/ # Tool-level tests\nβββ docs/ # Documentation (MkDocs)\nβββ plan/ # Implementation plans (not in VCS deliverables)\nβββ scripts/ # Build and utility scripts\n```\n\n### Code Standards\n\n- **Python**: Ruff for linting (line-length 100)\n- **TypeScript**: ESLint for linting\n- **Commit Messages**: Conventional Commits format\n\n### Testing\n\n```bash\n# Python backend tests (~1800+ tests)\nuv run pytest\n\n# Skip sandbox/subprocess tests for quick feedback\nuv run pytest -m \"not sandbox and not subprocess\"\n\n# Frontend tests\ncd apps/desktop\nnpm run test\n```\n\n---\n\n## Documentation\n\n- [Getting Started](docs/getting-started.md)\n- [Architecture](docs/architecture.md)\n- [Configuration](docs/configuration.md)\n- [MCP Integration](docs/mcp-integration.md)\n- [Developer Guide](docs/developer-guide.md)\n- [Internal Alpha Smoke](docs/internal-alpha-smoke.md)\n\n---\n\n## License\n\n[MIT License](LICENSE)\n\n---\n\n## Contributing\n\nContributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details.\n"}, "fb5b53c93bf536b16ffe3be2f5806e3f49a6b7b9": {"t": 1785771674.5593827, "n": 12770, "h": "84be61bfad84c40e", "c": "# MiQi\n\n\n πββ¬πͺΆ A lightweight, extensible personal AI agent framework with a modern desktop interface\n
\n\n\n \n \n \n \n
\n\n---\n\n## Overview\n\nMiQi is a personal AI agent framework that combines a powerful **Python runtime engine** with an **Electron desktop application**. It provides a typed application server protocol, request validation, multi-provider LLM support, sandboxed command execution, and a plugin/skills ecology β all with a local-first, privacy-respecting architecture.\n\n### Core Positioning\n\n- π― **Personal AI Agent** β not just a chatbot: persistent memory, learned skills, file operations, and scheduled tasks\n- π§ **Highly Extensible** β MCP protocol for external tools, custom skills, and pluggable LLM providers\n- π₯οΈ **Native Desktop Experience** β Electron with system-level integration (WSL2 sandbox, filesystem operations)\n- π **Local-First** β all data stored locally; non-destructive file editing with versioned snapshots\n- π **Typed Application Protocol** β typed AppServer with JSON Schema catalog, method stability tracking, and handler-boundary validation\n\n### Tech Stack\n\n| Layer | Technology | Version |\n|-------|-----------|---------|\n| Desktop Framework | Electron | 35.2 |\n| Frontend UI | React + TypeScript | 19.1 / 5.8 |\n| CSS | Tailwind CSS 4 | 4.x |\n| Component Library | Radix UI + Lucide Icons | β |\n| Python Runtime | Python (asyncio) | 3.11+ |\n| Data Validation | Pydantic v2 | 2.12+ |\n| CLI Framework | Typer | 0.20+ |\n| Build (Desktop) | electron-vite + electron-builder | 3.1 / 26.0 |\n| Build (Python) | PyInstaller + Hatchling | 6.20+ |\n\n---\n\n## Key Features\n\n| Feature | Description |\n|---|---|\n| **Smart Chat** | Natural language conversation with streaming responses and tool-call progress |\n| **Multi-Provider** | OpenAI, Anthropic, Gemini, OpenRouter, DeepSeek, and more β with provider resilience |\n| **Typed Protocol** | Typed AppServer with method specs, JSON Schema catalog, and handler-boundary validation |\n| **Memory System** | Long-term memory snapshots, self-improvement lessons, and cross-session recall |\n| **Task Scheduler** | Cron-based scheduled tasks with timezone support |\n| **Skill System** | Create, upload, and manage agent skills; SkillHub registry integration |\n| **Plugin Ecology** | MCP servers, plugins, and marketplace with deterministic catalog |\n| **Sandbox Execution** | bwrap-based sandbox with LANDLOCK filesystem rules, streaming I/O, and process lifecycle |\n| **File Management** | Workspace FS with watch, fuzzy search, snapshot/versioning, and non-destructive editing |\n| **Replay & Debug** | Deterministic replay of turns, timeline, and messages for inspection |\n| **Session Management** | Browse, search, archive, import/export conversation history |\n| **Desktop App** | 15+ feature pages with real-time streaming, typewriter animation, and context menus |\n\n---\n\n## Quick Start\n\n### Prerequisites\n\n- **Python 3.11+** β to run MiQi backend\n- **Node.js 20+** β to run Electron frontend\n- **uv** β Python package manager (recommended)\n\n### Installation\n\n```bash\n# 1. Clone the repository\ngit clone http://git.miqroera.com/intership/miqi-desktop.git\ncd miqi-desktop\n\n# 2. Install Python dependencies\nuv sync\n\n# 3. Install frontend dependencies\ncd apps/desktop\nnpm install\n```\n\n### Development Mode\n\n```bash\n# Start Electron dev server with hot-reload\ncd apps/desktop\nnpm run dev\n```\n\n### Production Build\n\n**One-step build** (recommended):\n\n```bash\ncd apps/desktop\nnpm run build:all # Python backend β Frontend compile β Electron package\n```\n\n**Step-by-step build**:\n\n```bash\ncd apps/desktop\n\n# 1. Build Python backend (generates dist/miqi-bridge.exe)\nnpm run build:bridge\n\n# 2. Compile frontend\nnpm run build\n\n# 3. Package as desktop application\nnpx electron-builder --win --publish never\n```\n\nThe packaged `miqi-bridge.exe` is a self-contained binary (PyInstaller onefile) that includes Python and all dependencies β no system Python installation required on the target machine. It also supports a `--check` flag for environment validation:\n\n```bash\nmiqi-bridge.exe --check\n# Output: {\"ok\": true, \"python_version\": \"3.12.10\", \"issues\": []}\n```\n\n---\n\n## Architecture\n\n```\nβββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ\nβ MiQi Desktop App β\nβββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€\nβ Electron Frontend β\nβ βββ React 19 + TypeScript β\nβ βββ Tailwind CSS 4 + shadcn/ui β\nβ βββ 15+ Feature Pages (Chat, Agents, Skills, MCPs, ...) β\nβββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€\nβ Bridge (IPC Communication) β\nβ βββ stdin/stdout JSON-line protocol β\nβ βββ State synchronization + Log forwarding β\nβ βββ BridgeRuntimeLoop (persistent asyncio event loop) β\nβββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€\nβ AppServer (Typed Protocol Layer) β\nβ βββ ProtocolRegistry (typed method specs) β\nβ βββ Typed Envelopes (Pydantic v2) β\nβ βββ JSON Schema Draft 2020-12 Catalog β\nβ βββ Handler Typed Validation β\nβββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€\nβ MiQi Runtime Engine β\nβ βββ RuntimeSession / TaskRunner / TurnRunner β\nβ βββ HistoryRuntime + LedgerRuntime (SQLite persistence) β\nβ βββ ContextRuntime (compaction, token budgeting) β\nβ βββ ThreadRuntime (fork, rollback, import/export) β\nβ βββ ReplayRuntime (deterministic replay inspection) β\nβββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€\nβ Execution & Sandbox β\nβ βββ ToolOrchestrator (approval β sandbox β execute) β\nβ βββ PermissionEngine + ApprovalPolicy + HookRuntime β\nβ βββ bwrap Sandbox (LANDLOCK, streaming, cancellation) β\nβ βββ Workbench Process Runtime (command/exec, process/*) β\nβββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€\nβ Tools & Integrations β\nβ βββ Built-in Tools (filesystem, shell, web, papers, ...) β\nβ βββ MCP Client (external tool servers) β\nβ βββ Plugin Manager + Skill Loader β\nβ βββ Office Document Tools (docx, pptx, xlsx) β\nβββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ\n```\n\n1. Launch the application\n2. Go through the setup wizard:\n - **Environment Check** β validates Python and dependencies (bundled exe auto-detects; dev mode checks system Python)\n - **WSL2 Setup** β (Windows only) auto-detects and installs WSL2 for sandbox support\n - **LLM Provider** β configure API keys and default model\n3. Start chatting with the AI agent\n### Protocol Method Families\n\n| Family | Scope | Methods |\n|--------|-------|---------|\n| `turn/*` | Turn | start, interrupt, steer |\n| `thread/*` | Thread | list, get, rollback, fork, delete, compact/start, inject_items |\n| `fs/*` | Filesystem | readFile, writeFile, createDirectory, getMetadata, readDirectory, remove, copy, watch, unwatch |\n| `fuzzyFileSearch/*` | Filesystem | sessionStart, sessionUpdate, sessionStop |\n| `command/exec` | Process | exec, exec/write, exec/resize, exec/terminate |\n| `process/*` | Process | spawn, writeStdin, resizePty, kill, list, get, snapshot |\n| `replay.*` | Debug | turns, timeline, messages |\n| `config/*` | Session | get, batchWrite |\n| `model/*` | Session | list, get |\n| `feature/*` | Session | list, set |\n| `permission/*` | Session | listProfiles, getProfile |\n| `plugin/*` | Session | list, install, uninstall, enable, disable, configure |\n| `skills/*` | Session | list, get, create, upload, delete, setExtraRoots |\n| `mcp/*` | Session | listServers, getServer, status |\n| `agent/*` | Session | list, get, spawn, kill |\n| `protocol/*` | Connection | catalog, method_names, schema |\n\n---\n\n## Configuration\n\nThe application configuration file is located at `~/.miqi/config.json`:\n\n```json\n{\n \"providers\": {\n \"openai\": { \"apiKey\": \"sk-...\" },\n \"anthropic\": { \"apiKey\": \"sk-ant-...\" }\n },\n \"agents\": {\n \"defaults\": {\n \"model\": \"claude-sonnet-4-6\",\n \"temperature\": 0.1,\n \"maxToolIterations\": 100\n }\n },\n \"tools\": {\n \"restrictToWorkspace\": true\n }\n}\n```\n\n### Environment Variables\n\n| Variable | Description |\n|---|---|\n| `MIQI_PYTHON_PATH` | Custom Python interpreter path |\n| `MIQI_AGENTS__DEFAULTS__MODEL` | Override default model |\n\n---\n\n## Development Guide\n\n### Project Structure\n\n```\nmiqi-desktop/\nβββ miqi/ # Python backend\nβ βββ runtime/ # Runtime engine (AppServer, Session, Turn, Thread, Replay, Agent, MCP, ...)\nβ βββ agent/ # Agent logic, tools, memory, trace, context compression, smart routing\nβ βββ bridge/ # Electron bridge service (IPC protocol)\nβ βββ bus/ # Internal message bus (async in/out queues)\nβ βββ execution/ # Tool orchestrator, permissions, approval, hooks, sandbox policy\nβ βββ providers/ # LLM provider implementations + resilience\nβ βββ protocol/ # Typed commands, events, permissions (runtime-frontend protocol)\nβ βββ channels/ # Chat channel adapters (Feishu, Slack, Discord, Telegram, ...)\nβ βββ sandbox/ # bwrap sandbox manager\nβ βββ skills/ # Built-in skills (cron, paper-research, feishu-report, ...)\nβ βββ session/ # Session management (Manager, SQLite store)\nβ βββ config/ # Configuration loader and schema\nβ βββ cli/ # CLI commands (agent, gateway, trace, config)\nβ βββ cron/ # Cron scheduler service\nβ βββ context/ # Context fragments, thread store\nβ βββ heartbeat/ # Heartbeat service\nβ βββ plan/ # Plan tracker and tool\nβ βββ documents/ # Office document tools (docx, pptx, xlsx)\nβ βββ observability/ # OpenTelemetry integration\nβ βββ server/ # Server assets and configuration\nβ βββ templates/ # Templates\nβ βββ tui/ # Terminal UI (Textual-based)\nβ βββ utils/ # Utility functions\nβββ apps/\nβ βββ desktop/ # Electron frontend\nβ βββ src/main/ # Main process (BridgeManager, IPC handlers)\nβ βββ src/renderer/ # Renderer (React pages and components)\nβ βββ src/preload/ # Preload scripts (contextBridge API)\nβββ tests/ # Test suite (~150+ test files)\nβ βββ runtime/ # Runtime unit and integration tests (~70+ files)\nβ βββ bridge/ # Bridge protocol and audit tests (~20+ files)\nβ βββ execution/ # Sandbox, permissions, orchestration tests\nβ βββ providers/ # LLM provider tests\nβ βββ protocol/ # Protocol commands/events/permissions tests\nβ βββ agent/tools/ # Tool-level tests\nβββ docs/ # Documentation (MkDocs)\nβββ plan/ # Implementation plans (not in VCS deliverables)\nβββ scripts/ # Build and utility scripts\n```\n\n### Code Standards\n\n- **Python**: Ruff for linting (line-length 100)\n- **TypeScript**: ESLint for linting\n- **Commit Messages**: Conventional Commits format\n\n### Testing\n\n```bash\n# Python backend tests (~1800+ tests)\nuv run pytest\n\n# Skip sandbox/subprocess tests for quick feedback\nuv run pytest -m \"not sandbox and not subprocess\"\n\n# Frontend tests\ncd apps/desktop\nnpm run test\n```\n\n---\n\n## Documentation\n\n- [Getting Started](docs/getting-started.md)\n- [Architecture](docs/architecture.md)\n- [Configuration](docs/configuration.md)\n- [MCP Integration](docs/mcp-integration.md)\n- [Developer Guide](docs/developer-guide.md)\n- [Internal Alpha Smoke](docs/internal-alpha-smoke.md)\n\n---\n\n## License\n\n[MIT License](LICENSE)\n\n---\n\n## Contributing\n\nContributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details.\n"}, "a09ba1e0bf0b59608c9b3e1cac8352b9c0b5263f": {"t": 1785771675.750211, "n": 11782, "h": "7aa076fb17aaaea2", "c": "# MiQi\n\n\n πββ¬πͺΆ A lightweight, extensible personal AI agent framework with a modern desktop interface\n
\n\n\n \n \n \n \n
\n\n---\n\n## Overview\n\nMiQi is a personal AI agent framework that combines a powerful **Python runtime engine** with an **Electron desktop application**. It provides a typed application server protocol, request validation, multi-provider LLM support, sandboxed command execution, and a plugin/skills ecology β all with a local-first, privacy-respecting architecture.\n\n### Core Positioning\n\n- π― **Personal AI Agent** β not just a chatbot: persistent memory, learned skills, file operations, and scheduled tasks\n- π§ **Highly Extensible** β MCP protocol for external tools, custom skills, and pluggable LLM providers\n- π₯οΈ **Native Desktop Experience** β Electron with system-level integration (WSL2 sandbox, filesystem operations)\n- π **Local-First** β all data stored locally; non-destructive file editing with versioned snapshots\n- π **Typed Application Protocol** β typed AppServer with JSON Schema catalog, method stability tracking, and handler-boundary validation\n\n### Tech Stack\n\n| Layer | Technology | Version |\n|-------|-----------|---------|\n| Desktop Framework | Electron | 35.2 |\n| Frontend UI | React + TypeScript | 19.1 / 5.8 |\n| CSS | Tailwind CSS 4 | 4.x |\n| Component Library | Radix UI + Lucide Icons | β |\n| Python Runtime | Python (asyncio) | 3.11+ |\n| Data Validation | Pydantic v2 | 2.12+ |\n| CLI Framework | Typer | 0.20+ |\n| Build (Desktop) | electron-vite + electron-builder | 3.1 / 26.0 |\n| Build (Python) | PyInstaller + Hatchling | 6.20+ |\n\n---\n\n## Key Features\n\n| Feature | Description |\n|---|---|\n| **Smart Chat** | Natural language conversation with streaming responses and tool-call progress |\n| **Multi-Provider** | OpenAI, Anthropic, Gemini, OpenRouter, DeepSeek, and more β with provider resilience |\n| **Typed Protocol** | Typed AppServer with method specs, JSON Schema catalog, and handler-boundary validation |\n| **Memory System** | Long-term memory snapshots, self-improvement lessons, and cross-session recall |\n| **Task Scheduler** | Cron-based scheduled tasks with timezone support |\n| **Skill System** | Create, upload, and manage agent skills; SkillHub registry integration |\n| **Plugin Ecology** | MCP servers, plugins, and marketplace with deterministic catalog |\n| **Sandbox Execution** | bwrap-based sandbox with LANDLOCK filesystem rules, streaming I/O, and process lifecycle |\n| **File Management** | Workspace FS with watch, fuzzy search, snapshot/versioning, and non-destructive editing |\n| **Replay & Debug** | Deterministic replay of turns, timeline, and messages for inspection |\n| **Session Management** | Browse, search, archive, import/export conversation history |\n| **Desktop App** | 15+ feature pages with real-time streaming, typewriter animation, and context menus |\n\n---\n\n## Quick Start\n\n### Prerequisites\n\n- **Python 3.11+** β to run MiQi backend\n- **Node.js 20+** β to run Electron frontend\n- **uv** β Python package manager (recommended)\n\n### Installation\n\n```bash\n# 1. Clone the repository\ngit clone http://git.miqroera.com/intership/miqi-desktop.git\ncd miqi-desktop\n\n# 2. Install Python dependencies\nuv sync\n\n# 3. Install frontend dependencies\ncd apps/desktop\nnpm install\n```\n\n### Development Mode\n\n```bash\n# Start Electron dev server with hot-reload\ncd apps/desktop\nnpm run dev\n```\n\n### Production Build\n\n```bash\n# Build frontend code\ncd apps/desktop\nnpm run build\n\n# Package as desktop application\nnpx electron-builder\n```\n\n---\n\n## Architecture\n\n```\nβββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ\nβ MiQi Desktop App β\nβββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€\nβ Electron Frontend β\nβ βββ React 19 + TypeScript β\nβ βββ Tailwind CSS 4 + shadcn/ui β\nβ βββ 15+ Feature Pages (Chat, Agents, Skills, MCPs, ...) β\nβββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€\nβ Bridge (IPC Communication) β\nβ βββ stdin/stdout JSON-line protocol β\nβ βββ State synchronization + Log forwarding β\nβ βββ BridgeRuntimeLoop (persistent asyncio event loop) β\nβββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€\nβ AppServer (Typed Protocol Layer) β\nβ βββ ProtocolRegistry (typed method specs) β\nβ βββ Typed Envelopes (Pydantic v2) β\nβ βββ JSON Schema Draft 2020-12 Catalog β\nβ βββ Handler Typed Validation β\nβββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€\nβ MiQi Runtime Engine β\nβ βββ RuntimeSession / TaskRunner / TurnRunner β\nβ βββ HistoryRuntime + LedgerRuntime (SQLite persistence) β\nβ βββ ContextRuntime (compaction, token budgeting) β\nβ βββ ThreadRuntime (fork, rollback, import/export) β\nβ βββ ReplayRuntime (deterministic replay inspection) β\nβββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€\nβ Execution & Sandbox β\nβ βββ ToolOrchestrator (approval β sandbox β execute) β\nβ βββ PermissionEngine + ApprovalPolicy + HookRuntime β\nβ βββ bwrap Sandbox (LANDLOCK, streaming, cancellation) β\nβ βββ Workbench Process Runtime (command/exec, process/*) β\nβββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€\nβ Tools & Integrations β\nβ βββ Built-in Tools (filesystem, shell, web, papers, ...) β\nβ βββ MCP Client (external tool servers) β\nβ βββ Plugin Manager + Skill Loader β\nβ βββ Office Document Tools (docx, pptx, xlsx) β\nβββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ\n```\n\n### Protocol Method Families\n\n| Family | Scope | Methods |\n|--------|-------|---------|\n| `turn/*` | Turn | start, interrupt, steer |\n| `thread/*` | Thread | list, get, rollback, fork, delete, compact/start, inject_items |\n| `fs/*` | Filesystem | readFile, writeFile, createDirectory, getMetadata, readDirectory, remove, copy, watch, unwatch |\n| `fuzzyFileSearch/*` | Filesystem | sessionStart, sessionUpdate, sessionStop |\n| `command/exec` | Process | exec, exec/write, exec/resize, exec/terminate |\n| `process/*` | Process | spawn, writeStdin, resizePty, kill, list, get, snapshot |\n| `replay.*` | Debug | turns, timeline, messages |\n| `config/*` | Session | get, batchWrite |\n| `model/*` | Session | list, get |\n| `feature/*` | Session | list, set |\n| `permission/*` | Session | listProfiles, getProfile |\n| `plugin/*` | Session | list, install, uninstall, enable, disable, configure |\n| `skills/*` | Session | list, get, create, upload, delete, setExtraRoots |\n| `mcp/*` | Session | listServers, getServer, status |\n| `agent/*` | Session | list, get, spawn, kill |\n| `protocol/*` | Connection | catalog, method_names, schema |\n\n---\n\n## Configuration\n\nThe application configuration file is located at `~/.miqi/config.json`:\n\n```json\n{\n \"providers\": {\n \"openai\": { \"apiKey\": \"sk-...\" },\n \"anthropic\": { \"apiKey\": \"sk-ant-...\" }\n },\n \"agents\": {\n \"defaults\": {\n \"model\": \"claude-sonnet-4-6\",\n \"temperature\": 0.1,\n \"maxToolIterations\": 100\n }\n },\n \"tools\": {\n \"restrictToWorkspace\": true\n }\n}\n```\n\n### Environment Variables\n\n| Variable | Description |\n|---|---|\n| `MIQI_PYTHON_PATH` | Custom Python interpreter path |\n| `MIQI_AGENTS__DEFAULTS__MODEL` | Override default model |\n\n---\n\n## Development Guide\n\n### Project Structure\n\n```\nmiqi-desktop/\nβββ miqi/ # Python backend\nβ βββ runtime/ # Runtime engine (AppServer, Session, Turn, Thread, Replay, Agent, MCP, ...)\nβ βββ agent/ # Agent logic, tools, memory, trace, context compression, smart routing\nβ βββ bridge/ # Electron bridge service (IPC protocol)\nβ βββ bus/ # Internal message bus (async in/out queues)\nβ βββ execution/ # Tool orchestrator, permissions, approval, hooks, sandbox policy\nβ βββ providers/ # LLM provider implementations + resilience\nβ βββ protocol/ # Typed commands, events, permissions (runtime-frontend protocol)\nβ βββ channels/ # Chat channel adapters (Feishu, Slack, Discord, Telegram, ...)\nβ βββ sandbox/ # bwrap sandbox manager\nβ βββ skills/ # Built-in skills (cron, paper-research, feishu-report, ...)\nβ βββ session/ # Session management (Manager, SQLite store)\nβ βββ config/ # Configuration loader and schema\nβ βββ cli/ # CLI commands (agent, gateway, trace, config)\nβ βββ cron/ # Cron scheduler service\nβ βββ context/ # Context fragments, thread store\nβ βββ heartbeat/ # Heartbeat service\nβ βββ plan/ # Plan tracker and tool\nβ βββ documents/ # Office document tools (docx, pptx, xlsx)\nβ βββ observability/ # OpenTelemetry integration\nβ βββ server/ # Server assets and configuration\nβ βββ templates/ # Templates\nβ βββ tui/ # Terminal UI (Textual-based)\nβ βββ utils/ # Utility functions\nβββ apps/\nβ βββ desktop/ # Electron frontend\nβ βββ src/main/ # Main process (BridgeManager, IPC handlers)\nβ βββ src/renderer/ # Renderer (React pages and components)\nβ βββ src/preload/ # Preload scripts (contextBridge API)\nβββ tests/ # Test suite (~150+ test files)\nβ βββ runtime/ # Runtime unit and integration tests (~70+ files)\nβ βββ bridge/ # Bridge protocol and audit tests (~20+ files)\nβ βββ execution/ # Sandbox, permissions, orchestration tests\nβ βββ providers/ # LLM provider tests\nβ βββ protocol/ # Protocol commands/events/permissions tests\nβ βββ agent/tools/ # Tool-level tests\nβββ docs/ # Documentation (MkDocs)\nβββ plan/ # Implementation plans (not in VCS deliverables)\nβββ scripts/ # Build and utility scripts\n```\n\n### Code Standards\n\n- **Python**: Ruff for linting (line-length 100)\n- **TypeScript**: ESLint for linting\n- **Commit Messages**: Conventional Commits format\n\n### Testing\n\n```bash\n# Python backend tests (~1800+ tests)\nuv run pytest\n\n# Skip sandbox/subprocess tests for quick feedback\nuv run pytest -m \"not sandbox and not subprocess\"\n\n# Frontend tests\ncd apps/desktop\nnpm run test\n```\n\n---\n\n## Documentation\n\n- [Getting Started](docs/getting-started.md)\n- [Architecture](docs/architecture.md)\n- [Configuration](docs/configuration.md)\n- [MCP Integration](docs/mcp-integration.md)\n- [Developer Guide](docs/developer-guide.md)\n- [Internal Alpha Smoke](docs/internal-alpha-smoke.md)\n\n---\n\n## License\n\n[MIT License](LICENSE)\n\n---\n\n## Contributing\n\nContributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details.\n"}, "bb6122c0c4edc55e69c1fe2122effbefbbadbed1": {"t": 1785771677.2536845, "n": 10734, "h": "e3759b6ede0876ab", "c": "# MiQi\n\n\n πββ¬πͺΆ A lightweight, extensible personal AI agent framework with a modern desktop interface\n
\n\n\n \n \n \n \n
\n\n---\n\n## Overview\n\nMiQi is a personal AI agent framework that combines a powerful **Python runtime engine** with an **Electron desktop application**. It provides a Codex-style application server protocol, typed request validation, multi-provider LLM support, sandboxed command execution, and a plugin/skills ecology β all with a local-first, privacy-respecting architecture.\n\n### Core Positioning\n\n- π― **Personal AI Agent** β not just a chatbot: persistent memory, learned skills, file operations, and scheduled tasks\n- π§ **Highly Extensible** β MCP protocol for external tools, custom skills, and pluggable LLM providers\n- π₯οΈ **Native Desktop Experience** β Electron with system-level integration (WSL2 sandbox, filesystem operations)\n- π **Local-First** β all data stored locally; non-destructive file editing with versioned snapshots\n- π **Codex-Style Protocol** β typed AppServer with JSON Schema catalog, method stability tracking, and handler-boundary validation\n\n### Tech Stack\n\n| Layer | Technology | Version |\n|-------|-----------|---------|\n| Desktop Framework | Electron | 35.2 |\n| Frontend UI | React + TypeScript | 19.1 / 5.8 |\n| CSS | Tailwind CSS 4 | 4.x |\n| Component Library | Radix UI + Lucide Icons | β |\n| Python Runtime | Python (asyncio) | 3.11+ |\n| Data Validation | Pydantic v2 | 2.12+ |\n| CLI Framework | Typer | 0.20+ |\n| Build (Desktop) | electron-vite + electron-builder | 3.1 / 26.0 |\n| Build (Python) | PyInstaller + Hatchling | 6.20+ |\n\n---\n\n## Key Features\n\n| Feature | Description |\n|---|---|\n| **Smart Chat** | Natural language conversation with streaming responses and tool-call progress |\n| **Multi-Provider** | OpenAI, Anthropic, Gemini, OpenRouter, DeepSeek, and more β with provider resilience |\n| **Codex Protocol** | Typed AppServer with 31 method specs, JSON Schema catalog, and handler-boundary validation |\n| **Memory System** | Long-term memory snapshots, self-improvement lessons, and cross-session recall |\n| **Task Scheduler** | Cron-based scheduled tasks with timezone support |\n| **Skill System** | Create, upload, and manage agent skills; SkillHub registry integration |\n| **Plugin Ecology** | MCP servers, plugins, and marketplace with deterministic catalog |\n| **Sandbox Execution** | bwrap-based sandbox with LANDLOCK filesystem rules, streaming I/O, and process lifecycle |\n| **File Management** | Workspace FS with watch, fuzzy search, snapshot/versioning, and non-destructive editing |\n| **Replay & Debug** | Deterministic replay of turns, timeline, and messages for inspection |\n| **Session Management** | Browse, search, archive, import/export conversation history |\n| **Desktop App** | 15+ feature pages with real-time streaming, typewriter animation, and context menus |\n\n---\n\n## Quick Start\n\n### Prerequisites\n\n- **Python 3.11+** β to run MiQi backend\n- **Node.js 20+** β to run Electron frontend\n- **uv** β Python package manager (recommended)\n\n### Installation\n\n```bash\n# 1. Clone the repository\ngit clone http://git.miqroera.com/intership/miqi-desktop.git\ncd miqi-desktop\n\n# 2. Install Python dependencies\nuv sync\n\n# 3. Install frontend dependencies\ncd apps/desktop\nnpm install\n```\n\n### Development Mode\n\n```bash\n# Start Electron dev server with hot-reload\ncd apps/desktop\nnpm run dev\n```\n\n### Production Build\n\n```bash\n# Build frontend code\ncd apps/desktop\nnpm run build\n\n# Package as desktop application\nnpx electron-builder\n```\n\n---\n\n## Architecture\n\n```\nβββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ\nβ MiQi Desktop App β\nβββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€\nβ Electron Frontend β\nβ βββ React 19 + TypeScript β\nβ βββ Tailwind CSS 4 + shadcn/ui β\nβ βββ 15+ Feature Pages (Chat, Agents, Skills, MCPs, ...) β\nβββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€\nβ Bridge (IPC Communication) β\nβ βββ stdin/stdout JSON-line protocol β\nβ βββ State synchronization + Log forwarding β\nβ βββ BridgeRuntimeLoop (persistent asyncio event loop) β\nβββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€\nβ AppServer (Codex-Style Protocol) β\nβ βββ ProtocolRegistry (31 typed method specs) β\nβ βββ Typed Envelopes (Pydantic v2) β\nβ βββ JSON Schema Draft 2020-12 Catalog β\nβ βββ Turn Handler Typed Validation β\nβββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€\nβ MiQi Runtime Engine β\nβ βββ RuntimeSession / TaskRunner / TurnRunner β\nβ βββ HistoryRuntime + LedgerRuntime (SQLite persistence) β\nβ βββ ContextRuntime (compaction, token budgeting) β\nβ βββ ThreadRuntime (fork, rollback, import/export) β\nβ βββ ReplayRuntime (deterministic replay inspection) β\nβββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€\nβ Execution & Sandbox β\nβ βββ ToolOrchestrator (approval β sandbox β execute) β\nβ βββ PermissionEngine + ApprovalPolicy + HookRuntime β\nβ βββ bwrap Sandbox (LANDLOCK, streaming, cancellation) β\nβ βββ Workbench Process Runtime (command/exec, process/*) β\nβββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€\nβ Tools & Integrations β\nβ βββ Built-in Tools (filesystem, shell, web, papers, ...) β\nβ βββ MCP Client (external tool servers) β\nβ βββ Plugin Manager + Skill Loader β\nβ βββ Office Document Tools (docx, pptx, xlsx) β\nβββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ\n```\n\n### Codex Protocol Method Families\n\n| Family | Scope | Methods |\n|--------|-------|---------|\n| `turn/*` | Turn | start, interrupt, steer |\n| `thread/*` | Thread | list, get, rollback, fork, delete, compact/start, inject_items |\n| `fs/*` | Filesystem | readFile, writeFile, createDirectory, getMetadata, readDirectory, remove, copy, watch, unwatch |\n| `fuzzyFileSearch/*` | Filesystem | sessionStart, sessionUpdate, sessionStop |\n| `command/exec` | Process | exec, exec/write, exec/resize, exec/terminate |\n| `process/*` | Process | spawn, writeStdin, resizePty, kill, list, get, snapshot |\n| `replay.*` | Debug | turns, timeline, messages |\n| `config/*` | Session | get, batchWrite |\n| `model/*` | Session | list, get |\n| `feature/*` | Session | list, set |\n| `permission/*` | Session | listProfiles, getProfile |\n| `plugin/*` | Session | list, install, uninstall, enable, disable, configure |\n| `skills/*` | Session | list, get, create, upload, delete, setExtraRoots |\n| `mcp/*` | Session | listServers, getServer, status |\n| `agent/*` | Session | list, get, spawn, kill |\n| `protocol/*` | Connection | catalog, method_names, schema |\n\n---\n\n## Configuration\n\nThe application configuration file is located at `~/.miqi/config.json`:\n\n```json\n{\n \"providers\": {\n \"openai\": { \"apiKey\": \"sk-...\" },\n \"anthropic\": { \"apiKey\": \"sk-ant-...\" }\n },\n \"agents\": {\n \"defaults\": {\n \"model\": \"claude-sonnet-4-6\",\n \"temperature\": 0.1,\n \"maxToolIterations\": 100\n }\n },\n \"tools\": {\n \"restrictToWorkspace\": true\n }\n}\n```\n\n### Environment Variables\n\n| Variable | Description |\n|---|---|\n| `MIQI_PYTHON_PATH` | Custom Python interpreter path |\n| `MIQI_AGENTS__DEFAULTS__MODEL` | Override default model |\n\n---\n\n## Development Guide\n\n### Project Structure\n\n```\nmiqi-desktop/\nβββ miqi/ # Python backend\nβ βββ runtime/ # Runtime engine (AppServer, Session, Turn, Thread, Replay, ...)\nβ βββ agent/ # Agent logic, tools, memory, trace\nβ βββ bridge/ # Electron bridge service (IPC protocol)\nβ βββ execution/ # Sandbox, permissions, approval, hooks\nβ βββ providers/ # LLM provider implementations\nβ βββ channels/ # Chat channel adapters (Feishu, Slack, Discord, ...)\nβ βββ sandbox/ # bwrap sandbox manager\nβ βββ skills/ # Built-in skills (cron, paper-research, feishu-report, ...)\nβ βββ config/ # Configuration loader and schema\nβ βββ cli/ # CLI commands (agent, gateway, trace, config)\nβ βββ cron/ # Cron scheduler service\nβ βββ documents/ # Office document tools (docx, pptx, xlsx)\nβ βββ observability/ # OpenTelemetry integration\nβββ apps/\nβ βββ desktop/ # Electron frontend\nβ βββ src/main/ # Main process (BridgeManager, IPC handlers)\nβ βββ src/renderer/ # Renderer (React pages and components)\nβ βββ src/preload/ # Preload scripts (contextBridge API)\nβββ tests/ # Test suite (~1800+ tests)\nβ βββ runtime/ # Runtime unit and integration tests\nβ βββ bridge/ # Bridge protocol and audit tests\nβββ docs/ # Documentation (MkDocs)\nβββ plan/ # Implementation plans (not in VCS deliverables)\nβββ scripts/ # Build and utility scripts\n```\n\n### Code Standards\n\n- **Python**: Ruff for linting (line-length 100)\n- **TypeScript**: ESLint for linting\n- **Commit Messages**: Conventional Commits format\n\n### Testing\n\n```bash\n# Python backend tests (~1800+ tests)\nuv run pytest\n\n# Skip sandbox/subprocess tests for quick feedback\nuv run pytest -m \"not sandbox and not subprocess\"\n\n# Frontend tests\ncd apps/desktop\nnpm run test\n```\n\n---\n\n## Documentation\n\n- [Getting Started](docs/getting-started.md)\n- [Architecture](docs/architecture.md)\n- [Configuration](docs/configuration.md)\n- [MCP Integration](docs/mcp-integration.md)\n- [Developer Guide](docs/developer-guide.md)\n- [Internal Alpha Smoke](docs/internal-alpha-smoke.md)\n\n---\n\n## License\n\n[MIT License](LICENSE)\n\n---\n\n## Contributing\n\nContributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details.\n"}, "20f2b10f4c648b045b76eb1690cd435ef12b7f67": {"t": 1785771679.1773524, "n": 5721, "h": "518cee9080a4b81d", "c": "# MiQi Desktop\n\n\n πββ¬πͺΆ A lightweight, extensible personal AI agent with a modern desktop interface\n
\n\n\n \n \n \n \n
\n\n---\n\n## Overview\n\nMiQi Desktop is an Electron-based desktop application that provides a modern graphical interface for the MiQi AI agent. It combines powerful AI agent capabilities with an intuitive user interface, supporting chat interaction, memory management, task scheduling, and more.\n\n## Key Features\n\n| Feature | Description |\n|---|---|\n| **Smart Chat** | Natural language conversation with AI agent |\n| **Multi-provider Support** | Supports OpenAI, Anthropic, Gemini, OpenRouter, and more LLM providers |\n| **Memory System** | Manage long-term memory snapshots and self-improvement lessons |\n| **Session Management** | Browse, search, and compact conversation history |\n| **Task Scheduler** | Create and manage scheduled tasks (Cron support) |\n| **Skill System** | Configure and enable various agent skills |\n| **File Management** | Workspace file system operations |\n| **Real-time Logs** | Monitor agent activity and debug information |\n\n---\n\n## Quick Start\n\n### Prerequisites\n\n- **Python 3.11+** - Required to run MiQi backend\n- **Node.js 20+** - Required to run Electron frontend\n- **uv** - Python package manager (recommended)\n\n### Installation\n\n```bash\n# 1. Clone the repository\ngit clone http://git.miqroera.com/intership/miqi-desktop.git\ncd miqi-desktop\n\n# 2. Install Python dependencies\nuv sync\n\n# 3. Install frontend dependencies\ncd apps/desktop\nnpm install\n```\n\n### Development Mode\n\n```bash\n# Start Electron dev server with hot-reload\ncd apps/desktop\nnpm run dev\n```\n\n### Production Build\n\n```bash\n# Build frontend code\ncd apps/desktop\nnpm run build\n\n# Package as desktop application\nnpx electron-builder\n```\n\n---\n\n## Usage Guide\n\n### First Run\n\n1. Launch the application\n2. Go through the setup wizard\n3. Configure LLM providers (e.g., OpenAI, OpenRouter)\n4. Enter your API keys\n5. Start chatting with the AI agent\n\n### Core Features\n\n**Chat Interface**\n- Markdown format support\n- Real-time tool call progress\n- Code syntax highlighting\n\n**Provider Management**\n- Add/edit LLM provider configurations\n- Test connection status\n- Switch default models\n\n**Memory Management**\n- View long-term memory snapshots\n- Manage self-improvement lessons\n- Import/export memory data\n\n**Task Scheduler**\n- Create scheduled tasks (Cron expressions supported)\n- Enable/disable tasks\n- Manually trigger task execution\n\n---\n\n## Configuration\n\nThe application configuration file is located at `~/.miqi/config.json` and contains the following main configuration options:\n\n```json\n{\n \"providers\": {\n \"openai\": { \"apiKey\": \"sk-...\" },\n \"anthropic\": { \"apiKey\": \"sk-ant-...\" }\n },\n \"agents\": {\n \"defaults\": {\n \"model\": \"gpt-4o\",\n \"temperature\": 0.1,\n \"maxToolIterations\": 50\n }\n },\n \"tools\": {\n \"restrictToWorkspace\": true\n }\n}\n```\n\n### Environment Variables\n\n| Variable | Description |\n|---|---|\n| `MIQI_PYTHON_PATH` | Custom Python interpreter path |\n| `MIQI_AGENTS__DEFAULTS__MODEL` | Override default model |\n\n---\n\n## Architecture\n\n```\nβββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ\nβ MiQi Desktop App β\nβββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€\nβ Electron Frontend β\nβ βββ React + TypeScript β\nβ βββ Tailwind CSS β\nβ βββ shadcn/ui Components β\nβββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€\nβ Bridge (IPC Communication) β\nβ βββ stdout/stderr JSON protocol β\nβ βββ State synchronization β\nβ βββ Log forwarding β\nβββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€\nβ MiQi Python Runtime β\nβ βββ RuntimeSession/TaskRunner/TurnRunner (Core runtime engine) β\nβ βββ Memory System β\nβ βββ Tool Registry β\nβ βββ Provider Interface β\nβββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ\n```\n\n---\n\n## Development Guide\n\n### Project Structure\n\n```\nmiqi-desktop/\nβββ miqi/ # Python backend code\nβ βββ agent/ # Core agent logic\nβ βββ bridge/ # Bridge service for Electron communication\nβ βββ providers/ # LLM provider implementations\nβ βββ ...\nβββ apps/\nβ βββ desktop/ # Electron frontend application\nβ βββ src/\nβ β βββ main/ # Main process code\nβ β βββ renderer/ # Renderer process code\nβ β βββ preload/ # Preload scripts\nβ βββ electron-builder.yml\nβββ ...\n```\n\n### Code Standards\n\n- **Python**: Ruff for linting\n- **TypeScript**: ESLint for linting\n- **Commit Messages**: Conventional Commits format\n\n### Testing\n\n```bash\n# Python backend tests\nuv run pytest\n\n# Frontend tests\ncd apps/desktop\nnpm run test\n```\n\n---\n\n## License\n\n[MIT License](LICENSE)\n\n---\n\n## Contributing\n\nContributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details.\n"}, "c01c52def1081a335fbada72a144ca631ed3f03d": {"t": 1785771680.719649, "n": 7290, "h": "4c3c61b17e778862", "c": "# MiQi Desktop\n\n\n πββ¬πͺΆ A lightweight, extensible personal AI agent with a modern desktop interface\n
\n\n\n \n \n \n \n
\n\n---\n\n## Overview\n\nMiQi Desktop is an Electron-based desktop application that provides a modern graphical interface for the MiQi AI agent. It combines powerful AI agent capabilities with an intuitive user interface, supporting chat interaction, memory management, task scheduling, and more.\n\n## Key Features\n\n| Feature | Description |\n|---|---|\n| **Smart Chat** | Natural language conversation with AI agent |\n| **Multi-provider Support** | Supports OpenAI, Anthropic, Gemini, OpenRouter, and more LLM providers |\n| **Multi-channel** | Connect via Feishu, WeChat, DingTalk and more message channels |\n| **Memory System** | Manage long-term memory snapshots and self-improvement lessons |\n| **Session Management** | Browse, search, and compact conversation history |\n| **Task Scheduler** | Create and manage scheduled tasks (Cron support) |\n| **Skill System** | Configure and enable various agent skills |\n| **Sandbox Isolation** | Per-session bwrap sandbox on WSL2 for safe code execution |\n| **File Management** | Workspace file system operations |\n| **Real-time Logs** | Monitor agent activity and debug information |\n\n---\n\n## Quick Start\n\n### Prerequisites\n\n- **Python 3.11+** - Required to run MiQi backend\n- **Node.js 20+** - Required to run Electron frontend\n- **uv** - Python package manager (recommended)\n\n### Installation\n\n```bash\n# 1. Clone the repository\ngit clone http://git.miqroera.com/intership/miqi-desktop.git\ncd miqi-desktop\n\n# 2. Install Python dependencies\nuv sync\n\n# 3. Install frontend dependencies\ncd apps/desktop\nnpm install\n```\n\n### Development Mode\n\n```bash\n# Start Electron dev server with hot-reload\ncd apps/desktop\nnpm run dev\n```\n\n### Production Build\n\n**One-step build** (recommended):\n\n```bash\ncd apps/desktop\nnpm run build:all # Python backend β Frontend compile β Electron package\n```\n\n**Step-by-step build**:\n\n```bash\ncd apps/desktop\n\n# 1. Build Python backend (generates dist/miqi-bridge.exe)\nnpm run build:bridge\n\n# 2. Compile frontend\nnpm run build\n\n# 3. Package as desktop application\nnpx electron-builder --win --publish never\n```\n\nThe packaged `miqi-bridge.exe` is a self-contained binary (PyInstaller onefile) that includes Python and all dependencies β no system Python installation required on the target machine. It also supports a `--check` flag for environment validation:\n\n```bash\nmiqi-bridge.exe --check\n# Output: {\"ok\": true, \"python_version\": \"3.12.10\", \"issues\": []}\n```\n\n---\n\n## Usage Guide\n\n### First Run\n\n1. Launch the application\n2. Go through the setup wizard:\n - **Environment Check** β validates Python and dependencies (bundled exe auto-detects; dev mode checks system Python)\n - **WSL2 Setup** β (Windows only) auto-detects and installs WSL2 for sandbox support\n - **LLM Provider** β configure API keys and default model\n3. Start chatting with the AI agent\n\n### Core Features\n\n**Chat Interface**\n- Markdown format support\n- Real-time tool call progress\n- Code syntax highlighting\n\n**Provider Management**\n- Add/edit LLM provider configurations\n- Test connection status\n- Switch default models\n\n**Memory Management**\n- View long-term memory snapshots\n- Manage self-improvement lessons\n- Import/export memory data\n\n**Task Scheduler**\n- Create scheduled tasks (Cron expressions supported)\n- Enable/disable tasks\n- Manually trigger task execution\n\n---\n\n## Configuration\n\nThe application configuration file is located at `~/.miqi/config.json` and contains the following main configuration options:\n\n```json\n{\n \"providers\": {\n \"openai\": { \"apiKey\": \"sk-...\" },\n \"anthropic\": { \"apiKey\": \"sk-ant-...\" }\n },\n \"agents\": {\n \"defaults\": {\n \"model\": \"gpt-4o\",\n \"temperature\": 0.1,\n \"maxToolIterations\": 50\n }\n },\n \"tools\": {\n \"restrictToWorkspace\": true\n }\n}\n```\n\n### Environment Variables\n\n| Variable | Description |\n|---|---|\n| `MIQI_PYTHON_PATH` | Custom Python interpreter path |\n| `MIQI_AGENTS__DEFAULTS__MODEL` | Override default model |\n\n---\n\n## Architecture\n\n```\nβββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ\nβ MiQi Desktop App β\nβββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€\nβ Electron Frontend β\nβ βββ React + TypeScript β\nβ βββ Tailwind CSS β\nβ βββ Radix UI Components β\nβββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€\nβ Bridge (IPC Communication) β\nβ βββ stdout/stderr JSON protocol β\nβ βββ State synchronization β\nβ βββ Log forwarding β\nβββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€\nβ MiQi Python Runtime β\nβ βββ AgentLoop (Core agent engine) β\nβ βββ Memory System β\nβ βββ Tool Registry β\nβ βββ Provider Interface β\nβ βββ Channel Bus (Feishu / WeChat / DingTalk) β\nβββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€\nβ Sandbox Layer (WSL2 + bwrap) β\nβ βββ Per-session isolation β\nβ βββ Filesystem sandboxing β\nβ βββ Safe code execution β\nβββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ\n```\n\n---\n\n## Development Guide\n\n### Project Structure\n\n```\nmiqi-desktop/\nβββ miqi/ # Python backend code\nβ βββ agent/ # Core agent logic & tool registry\nβ βββ bridge/ # Bridge service for Electron communication\nβ βββ providers/ # LLM provider implementations\nβ βββ channels/ # Message channel adapters (Feishu/WeChat/DingTalk)\nβ βββ sandbox/ # bwrap sandbox manager (WSL2)\nβ βββ ...\nβββ apps/\nβ βββ desktop/ # Electron frontend application\nβ βββ src/\nβ β βββ main/ # Main process (IPC handlers, BridgeManager)\nβ β βββ renderer/ # Renderer process (React UI)\nβ β βββ preload/ # Preload scripts (contextBridge)\nβ βββ electron-builder.yml\nβββ ...\n```\n\n### Code Standards\n\n- **Python**: Ruff for linting\n- **TypeScript**: ESLint for linting\n- **Commit Messages**: Conventional Commits format\n\n### Testing\n\n```bash\n# Python backend tests\nuv run pytest\n\n# Frontend tests\ncd apps/desktop\nnpm run test\n```\n\n---\n\n## License\n\n[MIT License](LICENSE)\n\n---\n\n## Contributing\n\nContributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details.\n"}, "3d9e26e5337aa292d5670c770861c1fa1982df43": {"t": 1785771682.2215066, "n": 7086, "h": "fcea5744bf586707", "c": "# MiQi Desktop\n\n\n πββ¬πͺΆ A lightweight, extensible personal AI agent with a modern desktop interface\n
\n\n\n \n \n \n \n
\n\n---\n\n## Overview\n\nMiQi Desktop is an Electron-based desktop application that provides a modern graphical interface for the MiQi AI agent. It combines powerful AI agent capabilities with an intuitive user interface, supporting chat interaction, memory management, task scheduling, and more.\n\n## Key Features\n\n| Feature | Description |\n|---|---|\n| **Smart Chat** | Natural language conversation with AI agent |\n| **Multi-provider Support** | Supports OpenAI, Anthropic, Gemini, OpenRouter, and more LLM providers |\n| **Multi-channel** | Connect via Feishu, WeChat, DingTalk and more message channels |\n| **Memory System** | Manage long-term memory snapshots and self-improvement lessons |\n| **Session Management** | Browse, search, and compact conversation history |\n| **Task Scheduler** | Create and manage scheduled tasks (Cron support) |\n| **Skill System** | Configure and enable various agent skills |\n| **Sandbox Isolation** | Per-session bwrap sandbox on WSL2 for safe code execution |\n| **File Management** | Workspace file system operations |\n| **Real-time Logs** | Monitor agent activity and debug information |\n\n---\n\n## Quick Start\n\n### Prerequisites\n\n- **Python 3.11+** - Required to run MiQi backend\n- **Node.js 20+** - Required to run Electron frontend\n- **uv** - Python package manager (recommended)\n\n### Installation\n\n```bash\n# 1. Clone the repository\ngit clone http://git.miqroera.com/intership/miqi-desktop.git\ncd miqi-desktop\n\n# 2. Install Python dependencies\nuv sync\n\n# 3. Install frontend dependencies\ncd apps/desktop\nnpm install\n```\n\n### Development Mode\n\n```bash\n# Start Electron dev server with hot-reload\ncd apps/desktop\nnpm run dev\n```\n\n### Production Build\n\n**One-step build** (recommended):\n\n```bash\ncd apps/desktop\nnpm run build:all # Python backend β Frontend compile β Electron package\n```\n\n**Step-by-step build**:\n\n```bash\ncd apps/desktop\n\n# 1. Build Python backend (generates dist/miqi-bridge.exe)\nnpm run build:bridge\n\n# 2. Compile frontend\nnpm run build\n\n# 3. Package as desktop application\nnpx electron-builder --win --publish never\n```\n\nThe packaged `miqi-bridge.exe` is a self-contained binary (PyInstaller onefile) that includes Python and all dependencies β no system Python installation required on the target machine. It also supports a `--check` flag for environment validation:\n\n```bash\nmiqi-bridge.exe --check\n# Output: {\"ok\": true, \"python_version\": \"3.12.10\", \"issues\": []}\n```\n\n---\n\n## Usage Guide\n\n### First Run\n\n1. Launch the application\n2. Go through the setup wizard:\n - **Environment Check** β validates Python and dependencies (bundled exe auto-detects; dev mode checks system Python)\n - **WSL2 Setup** β (Windows only) auto-detects and installs WSL2 for sandbox support\n - **LLM Provider** β configure API keys and default model\n3. Start chatting with the AI agent\n\n### Core Features\n\n**Chat Interface**\n- Markdown format support\n- Real-time tool call progress\n- Code syntax highlighting\n\n**Provider Management**\n- Add/edit LLM provider configurations\n- Test connection status\n- Switch default models\n\n**Memory Management**\n- View long-term memory snapshots\n- Manage self-improvement lessons\n- Import/export memory data\n\n**Task Scheduler**\n- Create scheduled tasks (Cron expressions supported)\n- Enable/disable tasks\n- Manually trigger task execution\n\n---\n\n## Configuration\n\nThe application configuration file is located at `~/.miqi/config.json` and contains the following main configuration options:\n\n```json\n{\n \"providers\": {\n \"openai\": { \"apiKey\": \"sk-...\" },\n \"anthropic\": { \"apiKey\": \"sk-ant-...\" }\n },\n \"agents\": {\n \"defaults\": {\n \"model\": \"gpt-4o\",\n \"temperature\": 0.1,\n \"maxToolIterations\": 50\n }\n },\n \"tools\": {\n \"restrictToWorkspace\": true\n }\n}\n```\n\n### Environment Variables\n\n| Variable | Description |\n|---|---|\n| `MIQI_PYTHON_PATH` | Custom Python interpreter path |\n| `MIQI_AGENTS__DEFAULTS__MODEL` | Override default model |\n\n---\n\n## Architecture\n\n```\nβββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ\nβ MiQi Desktop App β\nβββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€\nβ Electron Frontend β\nβ βββ React + TypeScript β\nβ βββ Tailwind CSS β\nβ βββ Radix UI Components β\nβββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€\nβ Bridge (IPC Communication) β\nβ βββ stdout/stderr JSON protocol β\nβ βββ State synchronization β\nβ βββ Log forwarding β\nβββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€\nβ MiQi Python Runtime β\nβ βββ AgentLoop (Core agent engine) β\nβ βββ Memory System β\nβ βββ Tool Registry β\nβ βββ Provider Interface β\nβ βββ Channel Bus (Feishu / WeChat / DingTalk) β\nβββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€\nβ Sandbox Layer (WSL2 + bwrap) β\nβ βββ Per-session isolation β\nβ βββ Filesystem sandboxing β\nβ βββ Safe code execution β\nβββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ\n```\n\n---\n\n## Development Guide\n\n### Project Structure\n\n```\nmiqi-desktop/\nβββ miqi/ # Python backend code\nβ βββ agent/ # Core agent logic\nβ βββ bridge/ # Bridge service for Electron communication\nβ βββ providers/ # LLM provider implementations\nβ βββ ...\nβββ apps/\nβ βββ desktop/ # Electron frontend application\nβ βββ src/\nβ β βββ main/ # Main process code\nβ β βββ renderer/ # Renderer process code\nβ β βββ preload/ # Preload scripts\nβ βββ electron-builder.yml\nβββ ...\n```\n\n### Code Standards\n\n- **Python**: Ruff for linting\n- **TypeScript**: ESLint for linting\n- **Commit Messages**: Conventional Commits format\n\n### Testing\n\n```bash\n# Python backend tests\nuv run pytest\n\n# Frontend tests\ncd apps/desktop\nnpm run test\n```\n\n---\n\n## License\n\n[MIT License](LICENSE)\n\n---\n\n## Contributing\n\nContributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details.\n"}, "d4cf1111ef1c8eccaa7b17c856e9d0be73076798": {"t": 1785771683.5375104, "n": 5716, "h": "54d44dbec9a2a33a", "c": "# MiQi Desktop\n\n\n πββ¬πͺΆ A lightweight, extensible personal AI agent with a modern desktop interface\n
\n\n\n \n \n \n \n
\n\n---\n\n## Overview\n\nMiQi Desktop is an Electron-based desktop application that provides a modern graphical interface for the MiQi AI agent. It combines powerful AI agent capabilities with an intuitive user interface, supporting chat interaction, memory management, task scheduling, and more.\n\n## Key Features\n\n| Feature | Description |\n|---|---|\n| **Smart Chat** | Natural language conversation with AI agent |\n| **Multi-provider Support** | Supports OpenAI, Anthropic, Gemini, OpenRouter, and more LLM providers |\n| **Memory System** | Manage long-term memory snapshots and self-improvement lessons |\n| **Session Management** | Browse, search, and compact conversation history |\n| **Task Scheduler** | Create and manage scheduled tasks (Cron support) |\n| **Skill System** | Configure and enable various agent skills |\n| **File Management** | Workspace file system operations |\n| **Real-time Logs** | Monitor agent activity and debug information |\n\n---\n\n## Quick Start\n\n### Prerequisites\n\n- **Python 3.11+** - Required to run MiQi backend\n- **Node.js 20+** - Required to run Electron frontend\n- **uv** - Python package manager (recommended)\n\n### Installation\n\n```bash\n# 1. Clone the repository\ngit clone http://git.miqroera.com/intership/miqi-desktop.git\ncd miqi-desktop\n\n# 2. Install Python dependencies\nuv sync\n\n# 3. Install frontend dependencies\ncd apps/desktop\nnpm install\n```\n\n### Development Mode\n\n```bash\n# Start Electron dev server with hot-reload\ncd apps/desktop\nnpm run dev\n```\n\n### Production Build\n\n```bash\n# Build frontend code\ncd apps/desktop\nnpm run build\n\n# Package as desktop application\nnpx electron-builder\n```\n\n---\n\n## Usage Guide\n\n### First Run\n\n1. Launch the application\n2. Go through the setup wizard\n3. Configure LLM providers (e.g., OpenAI, OpenRouter)\n4. Enter your API keys\n5. Start chatting with the AI agent\n\n### Core Features\n\n**Chat Interface**\n- Markdown format support\n- Real-time tool call progress\n- Code syntax highlighting\n\n**Provider Management**\n- Add/edit LLM provider configurations\n- Test connection status\n- Switch default models\n\n**Memory Management**\n- View long-term memory snapshots\n- Manage self-improvement lessons\n- Import/export memory data\n\n**Task Scheduler**\n- Create scheduled tasks (Cron expressions supported)\n- Enable/disable tasks\n- Manually trigger task execution\n\n---\n\n## Configuration\n\nThe application configuration file is located at `~/.miqi/config.json` and contains the following main configuration options:\n\n```json\n{\n \"providers\": {\n \"openai\": { \"apiKey\": \"sk-...\" },\n \"anthropic\": { \"apiKey\": \"sk-ant-...\" }\n },\n \"agents\": {\n \"defaults\": {\n \"model\": \"gpt-4o\",\n \"temperature\": 0.1,\n \"maxToolIterations\": 50\n }\n },\n \"tools\": {\n \"restrictToWorkspace\": true\n }\n}\n```\n\n### Environment Variables\n\n| Variable | Description |\n|---|---|\n| `MIQI_PYTHON_PATH` | Custom Python interpreter path |\n| `MIQI_AGENTS__DEFAULTS__MODEL` | Override default model |\n\n---\n\n## Architecture\n\n```\nβββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ\nβ MiQi Desktop App β\nβββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€\nβ Electron Frontend β\nβ βββ React + TypeScript β\nβ βββ Tailwind CSS β\nβ βββ shadcn/ui Components β\nβββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€\nβ Bridge (IPC Communication) β\nβ βββ stdout/stderr JSON protocol β\nβ βββ State synchronization β\nβ βββ Log forwarding β\nβββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€\nβ MiQi Python Runtime β\nβ βββ AgentLoop (Core agent engine) β\nβ βββ Memory System β\nβ βββ Tool Registry β\nβ βββ Provider Interface β\nβββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ\n```\n\n---\n\n## Development Guide\n\n### Project Structure\n\n```\nmiqi-desktop/\nβββ miqi/ # Python backend code\nβ βββ agent/ # Core agent logic\nβ βββ bridge/ # Bridge service for Electron communication\nβ βββ providers/ # LLM provider implementations\nβ βββ ...\nβββ apps/\nβ βββ desktop/ # Electron frontend application\nβ βββ src/\nβ β βββ main/ # Main process code\nβ β βββ renderer/ # Renderer process code\nβ β βββ preload/ # Preload scripts\nβ βββ electron-builder.yml\nβββ ...\n```\n\n### Code Standards\n\n- **Python**: Ruff for linting\n- **TypeScript**: ESLint for linting\n- **Commit Messages**: Conventional Commits format\n\n### Testing\n\n```bash\n# Python backend tests\nuv run pytest\n\n# Frontend tests\ncd apps/desktop\nnpm run test\n```\n\n---\n\n## License\n\n[MIT License](LICENSE)\n\n---\n\n## Contributing\n\nContributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details.\n"}, "b9f08bca92e25f98de8d057b827a03bc6cc9121c": {"t": 1785771685.429297, "n": 22762, "h": "a06da4e9c9c456f9", "c": "# MiQi\n\n\n πββ¬πͺΆ A lightweight, extensible personal AI agent framework for production automation and conversational workflows.\n
\n\n\n \n \n \n ![\"Ruff\"](\"https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json\")
\n ![\"uv\"](\"https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json\")
\n ![\"Docker](\"https://img.shields.io/badge/docker-supported-2496ED?logo=docker&logoColor=white\")
\n
\n\n---\n\n## Overview\n\nMiQi is a compact AI agent runtime designed for developers who want a self-hosted, programmable assistant. It connects to any OpenAI-compatible LLM provider and exposes a rich toolset β file operations, shell execution, web search, scheduled tasks, sub-agents, and external MCP servers β all configurable via a single JSON file.\n\nMiQi is a domain-focused evolution of the upstream [`nanobot`](https://github.com/HKUDS/nanobot) project. Full credit to the upstream team for the excellent engineering baseline in runtime design and tool abstraction.\n\n> **Reference baseline:** `nanobot` @ [`30361c9`](https://github.com/HKUDS/nanobot/commit/30361c9307f9014f49530d80abd5717bc97f554a) (2026-02-23)\n\n---\n\n## Features\n\n| Category | Capabilities |\n|---|---|\n| **LLM Providers** | OpenRouter, OpenAI, Anthropic, DeepSeek, Gemini, Groq, Moonshot, MiniMax, ZhipuAI, DashScope (Qwen), SiliconFlow, VolcEngine, AiHubMix, vLLM, Ollama, and any OpenAI-compatible endpoint |\n| **Built-in Tools** | File system, shell, web fetch/search, paper research (search/details/download), cron scheduler, sub-agent spawning |\n| **Channels** | Feishu is wired in the packaged gateway today; additional adapter modules for Telegram/Discord/Slack/Email/QQ/DingTalk/MoChat are present in the repository for extension work |\n| **MCP Integration** | Connect any MCP-compatible tool server (e.g. [feishu-mcp](https://github.com/lichman0405/feishu-mcp)) |\n| **Memory** | RAM-first long-term snapshots, lesson extraction, and append-only JSONL session history under the configured workspace |\n| **Agent Runtime** | Safe concurrent tool execution for read-only batches, iteration-budget safeguards, MCP heartbeat progress, and optional embedded routing/compression hooks |\n| **Extensibility** | MCP server integration, skill files, custom provider plugins |\n| **CLI** | Interactive onboarding, agent chat, gateway mode, cron and memory management |\n\n---\n\n## Quick Start\n\n### Installation\n\n#### Using [uv](https://docs.astral.sh/uv/) (Recommended)\n\n[uv](https://github.com/astral-sh/uv) is a fast Python package manager that uses the `uv.lock` lockfile shipped in this repository for reproducible installs.\n\n```bash\n# Install uv (skip if already installed)\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n# Verify uv\nuv --version # e.g. uv 0.11.x\n\n# Clone and install\ngit clone https://github.com/lichman0405/MiQi.git\ncd MiQi\nuv sync # creates .venv, installs locked dependencies + miqi\n\n# Activate the virtual environment\nsource .venv/bin/activate\n\n# Verify\nmiqi --version\n```\n\n#### Using pip\n\n```bash\ngit clone https://github.com/lichman0405/MiQi.git\ncd MiQi\n\npython3 -m venv .venv\nsource .venv/bin/activate\n\npip install --upgrade pip\npip install -e .\n\nmiqi --version\n```\n\n### First Run\n\n```bash\n# Interactive setup wizard β configures your provider, model, and identity\nmiqi onboard\n\n# Send a one-shot message\nmiqi agent -m \"hello\"\n\n# Start an interactive chat session\nmiqi agent\n\n# Launch the long-running gateway (channels + scheduled jobs)\nmiqi gateway\n```\n\n`miqi onboard` now also supports:\n\n- Paper research tool configuration (`tools.papers` provider, API key, limits)\n\n---\n\n## Installation Options\n\n### With Dev Dependencies\n\n```bash\n# uv (recommended) β installs pytest, ruff, pytest-asyncio\nuv sync --extra dev\n\n# pip alternative\npip install -e '.[dev]'\n```\n\n### Docker (Recommended for Production)\n\n```bash\n# Start the gateway\ndocker compose up --build miqi-gateway\n\n# Run a one-off CLI command in the container\ndocker compose --profile cli run --rm miqi-cli status\n```\n\n**Runtime data directory mapping:**\n\n| Location | Path |\n|---|---|\n| Host | `~/.miqi` |\n| Container | `/home/miqi/.miqi` |\n\n> **Security:** The container runs as unprivileged user `miqi` (UID 1000) β not root. The gateway port (`18790`) is bound to `127.0.0.1` by default and is **not** exposed to the network. Use a reverse proxy (e.g. Nginx) to expose it externally.\n\n### Bare-Metal (Non-Docker) Deployment\n\nFor running the gateway directly on a Linux/macOS host as a long-running service:\n\n**1. Prepare configuration** (if not done already):\n\n```bash\n# Interactive setup β creates ~/.miqi/config.json\nmiqi onboard\n\n# Verify the config\nmiqi status\n```\n\n**2. (Optional) Set up MCP servers:**\n\n```bash\nbash scripts/setup_mcps.sh # install isolated venvs\nbash scripts/configure_mcps.sh # register MCPs into config\n```\n\n> **Note β single source of truth for LLM-backed MCPs.**\n> Any bundled MCP that needs an LLM (currently `pdf2zh`) automatically uses\n> the model and provider you set with `miqi onboard` / `miqi config defaults`.\n> To switch the model for everything in one step, run:\n>\n> ```bash\n> miqi config defaults --model \n> miqi config sync-llm # also performed at the end of configure_mcps.sh\n> ```\n>\n> Do **not** pass `-m` / `--model` to `miqi config pdf2zh` directly β the\n> next `sync-llm` run would overwrite it anyway.\n\n**3. Run with systemd** (Linux, recommended):\n\nCreate `/etc/systemd/system/miqi.service`:\n\n```ini\n[Unit]\nDescription=MiQi AI Agent Gateway\nAfter=network.target\n\n[Service]\nType=simple\nUser=miqi\nWorkingDirectory=/home/miqi\nExecStart=/home/miqi/.local/bin/miqi gateway\nRestart=on-failure\nRestartSec=10\nEnvironment=HOME=/home/miqi\n\n[Install]\nWantedBy=multi-user.target\n```\n\n```bash\nsudo systemctl daemon-reload\nsudo systemctl enable --now miqi\nsudo journalctl -u miqi -f # tail logs\n```\n\nOn macOS, use `launchd` or a process manager like `supervisord` instead.\n\n**4. Reverse proxy** (optional, for external access):\n\nThe gateway listens on `127.0.0.1:18790`. To expose it, place it behind Nginx:\n\n```nginx\nserver {\n listen 443 ssl;\n server_name miqi.example.com;\n\n location / {\n proxy_pass http://127.0.0.1:18790;\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n }\n}\n```\n\n### Upgrading\n\n```bash\ncd MiQi\ngit pull --recurse-submodules\n\n# Reinstall core\nuv sync # or: pip install -e .\n\nbash scripts/setup_mcps.sh # update MCP venvs\nbash scripts/configure_mcps.sh # re-register MCPs (idempotent)\n# then restart the gateway (systemctl restart miqi / docker compose up --build)\n```\n\n> **Note:** The Docker image does **not** include MCP submodules β MCP servers run as separate stdio subprocesses on the host. When using Docker, mount or install MCP venvs on the host and configure `tools.mcpServers` commands to point at host-side interpreters, or run MCP servers as separate containers and use HTTP transport (`url` instead of `command`).\n\n---\n\n## Configuration\n\nMiQi reads from `~/.miqi/config.json`. The interactive wizard (`miqi onboard`) can generate this file for you.\n\n**Default paths:**\n\n| Item | Path |\n|---|---|\n| Config file | `~/.miqi/config.json` |\n| Workspace | `~/.miqi/workspace` |\n\n### Configuration Skeleton\n\n```json\n{\n \"providers\": {\n \"openrouter\": {\n \"apiKey\": \"sk-or-v1-xxx\"\n }\n },\n \"agents\": {\n \"defaults\": {\n \"model\": \"anthropic/claude-opus-4-5\",\n \"name\": \"miqi\",\n \"temperature\": 0.1\n }\n },\n \"channels\": {},\n \"tools\": {},\n \"heartbeat\": {\n \"enabled\": true,\n \"intervalSeconds\": 1800\n }\n}\n```\n\n### Key Sections\n\n- **`providers`** β API keys, custom `apiBase` URLs, and optional `extraHeaders` (for example `APP-Code` on AiHubMix) for each provider.\n- **`agents.defaults`** β Default model, temperature, `maxTokens`, `maxToolIterations`, `maxToolResultChars`, `contextLimitChars`, `memoryWindow`, and the workspace path.\n- **`agents.memory`** β Flush cadence plus in-memory short-term window sizing. Runtime files live under `/memory/`.\n- **`agents.sessions`** β JSONL session compaction thresholds and saved-tool-result truncation. The schema also exposes `useSqlite` for the shipped SQLite+FTS5 session backend module, but the packaged CLI/gateway path still instantiates the JSONL `SessionManager` by default.\n- **`agents.selfImprovement`** β Lesson extraction settings such as `maxLessonsInPrompt`, `minLessonConfidence`, `feedbackMaxMessageChars`, and promotion controls.\n- **`agents.smartRouting`** β Cheap-model routing settings. `AgentLoop` supports them programmatically; the packaged CLI/gateway path currently leaves this disabled unless you embed the runtime yourself.\n- **`agents.commandApproval`** β Schema for interactive dangerous-command approval. The repository ships the helper module, while the default `exec` tool path still relies on static deny-pattern guards.\n- **`channels`** β Global channel delivery flags (`sendProgress`, `sendToolHints`, `sendQueueNotifications`) plus Feishu gateway configuration. Other adapter modules exist in the repo but are not currently surfaced by the public config schema.\n- **`gateway`** β HTTP gateway listen address (`host`, `port`; default `0.0.0.0:18790` for bare-metal runs). Docker Compose binds the published port to `127.0.0.1:18790` by default.\n- **`tools`** β Web/search/fetch behavior, paper research provider settings, shell execution policy (`tools.exec.timeout`, `tools.exec.envPassthrough`), the global `restrictToWorkspace` flag, and MCP server definitions.\n - **`tools.mcpServers..progressIntervalSeconds`** β Heartbeat interval for long-running MCP tools. Set `0` to disable. Default `15`.\n - **`tools.mcpServers..toolTimeout`** β Timeout before a single MCP tool call is cancelled. Default `30`.\n - **`tools.mcpServers..lazy`** β Register one lightweight gateway tool instead of all server tools up front.\n - **`tools.mcpServers..description`** β LLM-facing description for lazy gateway mode.\n- **`heartbeat`** β Periodic background prompts (`enabled`, `intervalSeconds`) for proactive behaviors.\n- **`cron`** β Scheduler-wide job timeout (`jobTimeoutSeconds`; default `86400`).\n\n> **Security:** Config files are automatically saved with `0600` permissions (owner-read-only) to protect API keys. See [docs/security.md](docs/security.md) for the current security model and operational limits.\n\n### Environment Variable Overrides\n\nEvery config field can be overridden at runtime via environment variables using the prefix `MIQI_` and `__` as the nesting delimiter:\n\n```bash\n# Override the default model\nMIQI_AGENTS__DEFAULTS__MODEL=deepseek/deepseek-chat miqi agent\n\n# Inject an API key without editing config.json\nMIQI_PROVIDERS__OPENROUTER__API_KEY=sk-or-v1-xxx miqi gateway\n```\n\nThis is particularly useful in containerised deployments where secrets are injected as environment variables rather than mounted files.\n\n---\n\n## CLI Reference\n\n**Agent & Gateway**\n\n| Command | Description |\n|---|---|\n| `miqi onboard` | Interactive setup wizard |\n| `miqi agent` | Start an interactive chat session |\n| `miqi agent -m \"\"` | Send a single prompt and exit |\n| `miqi gateway` | Run the long-running gateway (channels + cron) |\n\n**Status & Diagnostics**\n\n| Command | Description |\n|---|---|\n| `miqi status` | Show runtime and provider status |\n| `miqi channels status` | Show channel connection status |\n\n**Memory Management**\n\n| Command | Description |\n|---|---|\n| `miqi memory status` | Show memory snapshot and stats |\n| `miqi memory flush` | Force-persist pending memory updates immediately |\n| `miqi memory compact [--max-items N]` | Prune long-term snapshot to at most N items |\n| `miqi memory list [--limit N] [--session S]` | Browse long-term snapshot entries |\n| `miqi memory delete ` | Remove a snapshot entry by ID |\n| `miqi memory lessons status` | Show self-improvement lesson stats |\n| `miqi memory lessons list` | List lessons (filter by `--scope`, `--session`, `--limit`) |\n| `miqi memory lessons enable ` | Re-enable a disabled lesson |\n| `miqi memory lessons disable ` | Suppress a lesson from future prompts |\n| `miqi memory lessons delete ` | Permanently remove a lesson |\n| `miqi memory lessons compact [--max-lessons N]` | Prune lessons to at most N entries |\n| `miqi memory lessons reset` | Wipe all lessons |\n\n**Session Management**\n\n| Command | Description |\n|---|---|\n| `miqi session compact --session ` | Compact a single conversation session |\n| `miqi session compact --all` | Compact all stored sessions |\n\n**Cron Scheduler**\n\n| Command | Description |\n|---|---|\n| `miqi cron list` | List all scheduled jobs |\n| `miqi cron add` | Add a new scheduled job |\n| `miqi cron run ` | Trigger a job manually |\n| `miqi cron enable ` | Enable a job |\n| `miqi cron disable ` | Disable a job |\n| `miqi cron remove ` | Remove a job permanently |\n\n**Configuration**\n\n| Command | Description |\n|---|---|\n| `miqi config show` | Print all non-default config values |\n| `miqi config provider ` | Set or update a provider's API key / base URL |\n| `miqi config feishu` | One-shot Feishu channel + feishu-mcp setup |\n| `miqi config pdf2zh` | Configure pdf2zh MCP server (auto-fills LLM credentials) |\n| `miqi config mcp list` | List all configured MCP servers |\n| `miqi config mcp add ` | Add or update an MCP server (stdio or HTTP) |\n| `miqi config mcp remove ` | Remove an MCP server |\n\n---\n\n## Core Capabilities\n\n### Memory & Self-Improvement\n\nMiQi uses a RAM-first memory architecture:\n\n- **Session window** β unconsolidated recent context for fast recall, persisted by default as append-only JSONL files under `/sessions/`\n- **Long-term snapshots** β periodic persistence with audit trails under `/memory/`\n- **Lesson extraction** β automatically distills insights from user feedback and tool outcomes\n- **Configurable confidence thresholds** β controls promotion of lessons to long-term memory\n\n### Agent Runtime Controls\n\n- **Iteration budget** β the main loop injects pressure hints as it approaches `maxToolIterations`\n- **Concurrent dispatch** β safe read-only or path-disjoint tool batches run via `asyncio.gather`\n- **Embedded hooks** β the `AgentLoop` constructor exposes optional smart-routing and context-compression controls for programmatic use\n\n### Scheduled Tasks\n\nJobs can be defined as:\n\n- **Interval jobs** β run every N seconds/minutes/hours\n- **Cron expression jobs** β full cron syntax support\n- **One-time jobs** β execute at a specific datetime\n\nAll jobs can be toggled, triggered manually, or removed via the CLI.\n\n### MCP Integration\n\nConnect any MCP-compatible tool server and expose its tools directly to the agent. Define MCP servers under `tools.mcpServers` in your config. For example, connect [feishu-mcp](https://github.com/lichman0405/feishu-mcp) to bring Feishu collaboration capabilities (messages, calendar, tasks, documents) into the agent via a clean MCP interface.\n\nFor long-running MCP tools (e.g. scientific computing), MiQi automatically sends periodic heartbeat progress messages to the user so they know the task is still running. Configure `progressIntervalSeconds` per MCP server (default 15s), increase `toolTimeout` for compute-heavy operations, and use `lazy` mode when a server exposes a large tool surface.\n\n### Task Queue Awareness\n\nWhen multiple users send messages simultaneously (e.g. in a group chat), MiQi queues tasks and notifies each user of their queue position. Users see when their task starts processing and how many tasks are ahead. This is enabled by default via `channels.sendQueueNotifications`.\n\n---\n\n## Development\n\n### Prerequisites\n\n- Python 3.11+\n- Linux or macOS (recommended)\n\n### Run Tests\n\n```bash\nPYTHONPATH=. .venv/bin/pytest -q\n```\n\n### Lint\n\n```bash\n.venv/bin/ruff check .\n```\n\n---\n\n## Migration Guide\n\nIf upgrading from a previous version or migrating from `nanobot`:\n\n| Item | Old | New |\n|---|---|---|\n| Python package | `nanobot.*` | `miqi.*` |\n| CLI command | `assistant` | `miqi` |\n| Runtime directory | `~/.assistant` | `~/.miqi` |\n| Workspace directory | `~/.assistant/workspace` | `~/.miqi/workspace` |\n\nBackward-compatible fallbacks for old config and data paths are retained where possible.\n\n---\n\n## MCP Ecosystem\n\nMiQi ships with seven domain-specific MCP servers as git submodules under `mcps/`.\nThey cover porous-material science, epitaxial surface analysis, PDF translation, and team collaboration.\n\n### Bundled MCP Servers\n\n| Name | Submodule | Python | Description |\n|---|---|---|---|\n| **zeopp** | `mcps/zeopp-backend` | 3.10+ | Zeo++ porous material geometry (volume, pore size, channels) |\n| **raspa2** | `mcps/raspa-mcp` | 3.11+ | RASPA2 molecular simulation β input templates, output parsing |\n| **mofstructure** | `mcps/mofstructure-mcp` | 3.9+ | MOF structural analysis β building blocks, topology, metal nodes |\n| **mofchecker** | `mcps/mofchecker-mcp` | **<3.11** | MOF structure validation β CIF integrity, geometry defects |\n| **miqrophi** | `mcps/miqrophi-mcp` | 3.10+ | Epitaxial lattice matching β CIF surface analysis, substrate screening, strain calculation |\n| **pdf2zh** | `mcps/pdftranslate-mcp` | 3.10β3.12 | PDF paper translation preserving LaTeX layout (needs OpenAI key) |\n| **feishu** | `mcps/feishu-mcp` | 3.11+ | Feishu/Lark β messaging, docs, tasks (needs App ID & Secret) |\n\n### Setup\n\n**1. Clone with submodules** (one-time):\n\n```bash\ngit clone --recurse-submodules https://github.com/lichman0405/miqi.git\n# or, if you already cloned without --recurse-submodules:\ngit submodule update --init --recursive\n```\n\n**2. Install Python venvs** for each MCP:\n\n```bash\nbash scripts/setup_mcps.sh\n```\n\nThe script uses [`uv`](https://docs.astral.sh/uv/) and pins the correct Python version per MCP\n(notably `mofchecker` requires Python 3.10; `pdf2zh` requires β€3.12).\n\n**3. Register MCPs with miqi**:\n\n```bash\nbash scripts/configure_mcps.sh\n```\n\nThis calls `miqi config mcp add` for every server with recommended timeouts and lazy-mode settings.\n\n**4. Add credentials** for the two servers that need them β open `~/.miqi/config.json` and fill in:\n\n```jsonc\n\"tools\": {\n \"mcpServers\": {\n \"pdf2zh\": {\n \"env\": {\n \"OPENAI_BASE_URL\": \"https://api.openai.com/v1\",\n \"OPENAI_API_KEY\": \"sk-...\",\n \"OPENAI_MODEL\": \"gpt-4o\"\n }\n },\n \"feishu\": {\n \"env\": {\n \"FEISHU_APP_ID\": \"cli_...\",\n \"FEISHU_APP_SECRET\": \"...\"\n }\n }\n }\n}\n```\n\n> **Security note**: MCP subprocesses launched via the stdio transport inherit only a minimal environment\n> (`HOME`, `PATH`, `SHELL`, `USER`, `TERM`, `LOGNAME`) β your LLM provider API keys are never exposed\n> to MCP servers unless you explicitly add them to `cfg.env` as shown above.\n\n---\n\n## Documentation Index\n\n### Root Documents\n\n- [README.md](README.md)\n- [CHANGELOG.md](CHANGELOG.md)\n- [CONTRIBUTING.md](CONTRIBUTING.md)\n\n### Project Docs (`docs/`)\n\n- [docs/index.md](docs/index.md)\n- [docs/getting-started.md](docs/getting-started.md)\n- [docs/configuration.md](docs/configuration.md)\n- [docs/cli-reference.md](docs/cli-reference.md)\n- [docs/mcp-integration.md](docs/mcp-integration.md)\n- [docs/architecture.md](docs/architecture.md)\n- [docs/memory-system.md](docs/memory-system.md)\n- [docs/self-improvement.md](docs/self-improvement.md)\n- [docs/security.md](docs/security.md)\n- [docs/developer-guide.md](docs/developer-guide.md)\n- [docs/changelog.md](docs/changelog.md)\n\n### Scripts (`scripts/`)\n\n- [scripts/setup_mcps.sh](scripts/setup_mcps.sh) β Create isolated Python venvs for all bundled MCP servers\n- [scripts/configure_mcps.sh](scripts/configure_mcps.sh) β Register all bundled MCPs into `~/.miqi/config.json`\n\n### Skills Docs (`miqi/skills/`)\n\n- [miqi/skills/README.md](miqi/skills/README.md)\n- [miqi/skills/cron/SKILL.md](miqi/skills/cron/SKILL.md)\n- [miqi/skills/feishu-report/SKILL.md](miqi/skills/feishu-report/SKILL.md)\n- [miqi/skills/github/SKILL.md](miqi/skills/github/SKILL.md)\n- [miqi/skills/memory/SKILL.md](miqi/skills/memory/SKILL.md)\n- [miqi/skills/paper-research/SKILL.md](miqi/skills/paper-research/SKILL.md)\n- [miqi/skills/skill-creator/SKILL.md](miqi/skills/skill-creator/SKILL.md)\n- [miqi/skills/summarize/SKILL.md](miqi/skills/summarize/SKILL.md)\n- [miqi/skills/tmux/SKILL.md](miqi/skills/tmux/SKILL.md)\n- [miqi/skills/weather/SKILL.md](miqi/skills/weather/SKILL.md)\n- [miqi/skills/workspace-cleanup/SKILL.md](miqi/skills/workspace-cleanup/SKILL.md)\n\n### Template Docs (`miqi/templates/`)\n\n- [miqi/templates/AGENTS.md](miqi/templates/AGENTS.md)\n- [miqi/templates/HEARTBEAT.md](miqi/templates/HEARTBEAT.md)\n- [miqi/templates/SOUL.md](miqi/templates/SOUL.md)\n- [miqi/templates/TOOLS.md](miqi/templates/TOOLS.md)\n- [miqi/templates/USER.md](miqi/templates/USER.md)\n- [miqi/templates/memory/MEMORY.md](miqi/templates/memory/MEMORY.md)\n\n---\n\n## Desktop App (Electron)\n\nMiQi Desktop is a native desktop application built with Electron, providing a modern GUI interface for managing the MiQi AI agent.\n\n### Features\n\n- **Chat Interface** β Interactive chat session with the AI agent\n- **Provider Management** β Configure LLM providers and API keys\n- **Memory Management** β View and manage long-term memory snapshots and lessons\n- **Session Explorer** β Browse and compact conversation history\n- **Cron Scheduler** β Manage scheduled jobs\n- **Skill Management** β Configure and enable/disable agent skills\n- **Workspace Management** β File system operations\n- **Real-time Logs** β Monitor agent activity\n\n### Development\n\n**Prerequisites:**\n- Node.js 20+\n- npm or yarn\n\n**Installation:**\n\n```bash\ncd apps/desktop\nnpm install\n```\n\n**Development Mode:**\n\n```bash\n# Start the Electron app with hot-reload\nnpm run dev\n```\n\n**Build:**\n\n```bash\n# Build for production\nnpm run build\n```\n\n**Type Checking:**\n\n```bash\nnpm run typecheck\n```\n\n**Testing:**\n\n```bash\nnpm run test\n```\n\n### Runtime Bridge\n\nThe desktop app communicates with the MiQi Python runtime via a subprocess bridge. The `BridgeManager` handles:\n- Starting/stopping the MiQi gateway\n- IPC communication between Electron and Python\n- State synchronization\n- Log forwarding\n\n---\n\n## License\n\n[MIT](LICENSE)\n"}, "0423cfbb710d7c36487e36b8a6725e2cd7ce7749": {"t": 1785771689.8097417, "n": 21470, "h": "57e6e8332d14945d", "c": "# MiQi\n\n\n πββ¬πͺΆ A lightweight, extensible personal AI agent framework for production automation and conversational workflows.\n
\n\n\n \n \n \n \n \n \n
\n\n---\n\n## Overview\n\nMiQi is a compact AI agent runtime designed for developers who want a self-hosted, programmable assistant. It connects to any OpenAI-compatible LLM provider and exposes a rich toolset β file operations, shell execution, web search, scheduled tasks, sub-agents, and external MCP servers β all configurable via a single JSON file.\n\nMiQi is a domain-focused evolution of the upstream [`nanobot`](https://github.com/HKUDS/nanobot) project. Full credit to the upstream team for the excellent engineering baseline in runtime design and tool abstraction.\n\n> **Reference baseline:** `nanobot` @ [`30361c9`](https://github.com/HKUDS/nanobot/commit/30361c9307f9014f49530d80abd5717bc97f554a) (2026-02-23)\n\n---\n\n## Features\n\n| Category | Capabilities |\n|---|---|\n| **LLM Providers** | OpenRouter, OpenAI, Anthropic, DeepSeek, Gemini, Groq, Moonshot, MiniMax, ZhipuAI, DashScope (Qwen), SiliconFlow, VolcEngine, AiHubMix, vLLM, Ollama, and any OpenAI-compatible endpoint |\n| **Built-in Tools** | File system, shell, web fetch/search, paper research (search/details/download), cron scheduler, sub-agent spawning |\n| **Channels** | Feishu is wired in the packaged gateway today; additional adapter modules for Telegram/Discord/Slack/Email/QQ/DingTalk/MoChat are present in the repository for extension work |\n| **MCP Integration** | Connect any MCP-compatible tool server (e.g. [feishu-mcp](https://github.com/lichman0405/feishu-mcp)) |\n| **Memory** | RAM-first long-term snapshots, lesson extraction, and append-only JSONL session history under the configured workspace |\n| **Agent Runtime** | Safe concurrent tool execution for read-only batches, iteration-budget safeguards, MCP heartbeat progress, and optional embedded routing/compression hooks |\n| **Extensibility** | MCP server integration, skill files, custom provider plugins |\n| **CLI** | Interactive onboarding, agent chat, gateway mode, cron and memory management |\n\n---\n\n## Quick Start\n\n### Installation\n\n#### Using [uv](https://docs.astral.sh/uv/) (Recommended)\n\n[uv](https://github.com/astral-sh/uv) is a fast Python package manager that uses the `uv.lock` lockfile shipped in this repository for reproducible installs.\n\n```bash\n# Install uv (skip if already installed)\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n# Verify uv\nuv --version # e.g. uv 0.11.x\n\n# Clone and install\ngit clone https://github.com/lichman0405/MiQi.git\ncd MiQi\nuv sync # creates .venv, installs locked dependencies + miqi\n\n# Activate the virtual environment\nsource .venv/bin/activate\n\n# Verify\nmiqi --version\n```\n\n#### Using pip\n\n```bash\ngit clone https://github.com/lichman0405/MiQi.git\ncd MiQi\n\npython3 -m venv .venv\nsource .venv/bin/activate\n\npip install --upgrade pip\npip install -e .\n\nmiqi --version\n```\n\n### First Run\n\n```bash\n# Interactive setup wizard β configures your provider, model, and identity\nmiqi onboard\n\n# Send a one-shot message\nmiqi agent -m \"hello\"\n\n# Start an interactive chat session\nmiqi agent\n\n# Launch the long-running gateway (channels + scheduled jobs)\nmiqi gateway\n```\n\n`miqi onboard` now also supports:\n\n- Paper research tool configuration (`tools.papers` provider, API key, limits)\n\n---\n\n## Installation Options\n\n### With Dev Dependencies\n\n```bash\n# uv (recommended) β installs pytest, ruff, pytest-asyncio\nuv sync --extra dev\n\n# pip alternative\npip install -e '.[dev]'\n```\n\n### Docker (Recommended for Production)\n\n```bash\n# Start the gateway\ndocker compose up --build miqi-gateway\n\n# Run a one-off CLI command in the container\ndocker compose --profile cli run --rm miqi-cli status\n```\n\n**Runtime data directory mapping:**\n\n| Location | Path |\n|---|---|\n| Host | `~/.miqi` |\n| Container | `/home/miqi/.miqi` |\n\n> **Security:** The container runs as unprivileged user `miqi` (UID 1000) β not root. The gateway port (`18790`) is bound to `127.0.0.1` by default and is **not** exposed to the network. Use a reverse proxy (e.g. Nginx) to expose it externally.\n\n### Bare-Metal (Non-Docker) Deployment\n\nFor running the gateway directly on a Linux/macOS host as a long-running service:\n\n**1. Prepare configuration** (if not done already):\n\n```bash\n# Interactive setup β creates ~/.miqi/config.json\nmiqi onboard\n\n# Verify the config\nmiqi status\n```\n\n**2. (Optional) Set up MCP servers:**\n\n```bash\nbash scripts/setup_mcps.sh # install isolated venvs\nbash scripts/configure_mcps.sh # register MCPs into config\n```\n\n> **Note β single source of truth for LLM-backed MCPs.**\n> Any bundled MCP that needs an LLM (currently `pdf2zh`) automatically uses\n> the model and provider you set with `miqi onboard` / `miqi config defaults`.\n> To switch the model for everything in one step, run:\n>\n> ```bash\n> miqi config defaults --model \n> miqi config sync-llm # also performed at the end of configure_mcps.sh\n> ```\n>\n> Do **not** pass `-m` / `--model` to `miqi config pdf2zh` directly β the\n> next `sync-llm` run would overwrite it anyway.\n\n**3. Run with systemd** (Linux, recommended):\n\nCreate `/etc/systemd/system/miqi.service`:\n\n```ini\n[Unit]\nDescription=MiQi AI Agent Gateway\nAfter=network.target\n\n[Service]\nType=simple\nUser=miqi\nWorkingDirectory=/home/miqi\nExecStart=/home/miqi/.local/bin/miqi gateway\nRestart=on-failure\nRestartSec=10\nEnvironment=HOME=/home/miqi\n\n[Install]\nWantedBy=multi-user.target\n```\n\n```bash\nsudo systemctl daemon-reload\nsudo systemctl enable --now miqi\nsudo journalctl -u miqi -f # tail logs\n```\n\nOn macOS, use `launchd` or a process manager like `supervisord` instead.\n\n**4. Reverse proxy** (optional, for external access):\n\nThe gateway listens on `127.0.0.1:18790`. To expose it, place it behind Nginx:\n\n```nginx\nserver {\n listen 443 ssl;\n server_name miqi.example.com;\n\n location / {\n proxy_pass http://127.0.0.1:18790;\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n }\n}\n```\n\n### Upgrading\n\n```bash\ncd MiQi\ngit pull --recurse-submodules\n\n# Reinstall core\nuv sync # or: pip install -e .\n\nbash scripts/setup_mcps.sh # update MCP venvs\nbash scripts/configure_mcps.sh # re-register MCPs (idempotent)\n# then restart the gateway (systemctl restart miqi / docker compose up --build)\n```\n\n> **Note:** The Docker image does **not** include MCP submodules β MCP servers run as separate stdio subprocesses on the host. When using Docker, mount or install MCP venvs on the host and configure `tools.mcpServers` commands to point at host-side interpreters, or run MCP servers as separate containers and use HTTP transport (`url` instead of `command`).\n\n---\n\n## Configuration\n\nMiQi reads from `~/.miqi/config.json`. The interactive wizard (`miqi onboard`) can generate this file for you.\n\n**Default paths:**\n\n| Item | Path |\n|---|---|\n| Config file | `~/.miqi/config.json` |\n| Workspace | `~/.miqi/workspace` |\n\n### Configuration Skeleton\n\n```json\n{\n \"providers\": {\n \"openrouter\": {\n \"apiKey\": \"sk-or-v1-xxx\"\n }\n },\n \"agents\": {\n \"defaults\": {\n \"model\": \"anthropic/claude-opus-4-5\",\n \"name\": \"miqi\",\n \"temperature\": 0.1\n }\n },\n \"channels\": {},\n \"tools\": {},\n \"heartbeat\": {\n \"enabled\": true,\n \"intervalSeconds\": 1800\n }\n}\n```\n\n### Key Sections\n\n- **`providers`** β API keys, custom `apiBase` URLs, and optional `extraHeaders` (for example `APP-Code` on AiHubMix) for each provider.\n- **`agents.defaults`** β Default model, temperature, `maxTokens`, `maxToolIterations`, `maxToolResultChars`, `contextLimitChars`, `memoryWindow`, and the workspace path.\n- **`agents.memory`** β Flush cadence plus in-memory short-term window sizing. Runtime files live under `/memory/`.\n- **`agents.sessions`** β JSONL session compaction thresholds and saved-tool-result truncation. The schema also exposes `useSqlite` for the shipped SQLite+FTS5 session backend module, but the packaged CLI/gateway path still instantiates the JSONL `SessionManager` by default.\n- **`agents.selfImprovement`** β Lesson extraction settings such as `maxLessonsInPrompt`, `minLessonConfidence`, `feedbackMaxMessageChars`, and promotion controls.\n- **`agents.smartRouting`** β Cheap-model routing settings. `AgentLoop` supports them programmatically; the packaged CLI/gateway path currently leaves this disabled unless you embed the runtime yourself.\n- **`agents.commandApproval`** β Schema for interactive dangerous-command approval. The repository ships the helper module, while the default `exec` tool path still relies on static deny-pattern guards.\n- **`channels`** β Global channel delivery flags (`sendProgress`, `sendToolHints`, `sendQueueNotifications`) plus Feishu gateway configuration. Other adapter modules exist in the repo but are not currently surfaced by the public config schema.\n- **`gateway`** β HTTP gateway listen address (`host`, `port`; default `0.0.0.0:18790` for bare-metal runs). Docker Compose binds the published port to `127.0.0.1:18790` by default.\n- **`tools`** β Web/search/fetch behavior, paper research provider settings, shell execution policy (`tools.exec.timeout`, `tools.exec.envPassthrough`), the global `restrictToWorkspace` flag, and MCP server definitions.\n - **`tools.mcpServers..progressIntervalSeconds`** β Heartbeat interval for long-running MCP tools. Set `0` to disable. Default `15`.\n - **`tools.mcpServers..toolTimeout`** β Timeout before a single MCP tool call is cancelled. Default `30`.\n - **`tools.mcpServers..lazy`** β Register one lightweight gateway tool instead of all server tools up front.\n - **`tools.mcpServers..description`** β LLM-facing description for lazy gateway mode.\n- **`heartbeat`** β Periodic background prompts (`enabled`, `intervalSeconds`) for proactive behaviors.\n- **`cron`** β Scheduler-wide job timeout (`jobTimeoutSeconds`; default `86400`).\n\n> **Security:** Config files are automatically saved with `0600` permissions (owner-read-only) to protect API keys. See [docs/security.md](docs/security.md) for the current security model and operational limits.\n\n### Environment Variable Overrides\n\nEvery config field can be overridden at runtime via environment variables using the prefix `MIQI_` and `__` as the nesting delimiter:\n\n```bash\n# Override the default model\nMIQI_AGENTS__DEFAULTS__MODEL=deepseek/deepseek-chat miqi agent\n\n# Inject an API key without editing config.json\nMIQI_PROVIDERS__OPENROUTER__API_KEY=sk-or-v1-xxx miqi gateway\n```\n\nThis is particularly useful in containerised deployments where secrets are injected as environment variables rather than mounted files.\n\n---\n\n## CLI Reference\n\n**Agent & Gateway**\n\n| Command | Description |\n|---|---|\n| `miqi onboard` | Interactive setup wizard |\n| `miqi agent` | Start an interactive chat session |\n| `miqi agent -m \"\"` | Send a single prompt and exit |\n| `miqi gateway` | Run the long-running gateway (channels + cron) |\n\n**Status & Diagnostics**\n\n| Command | Description |\n|---|---|\n| `miqi status` | Show runtime and provider status |\n| `miqi channels status` | Show channel connection status |\n\n**Memory Management**\n\n| Command | Description |\n|---|---|\n| `miqi memory status` | Show memory snapshot and stats |\n| `miqi memory flush` | Force-persist pending memory updates immediately |\n| `miqi memory compact [--max-items N]` | Prune long-term snapshot to at most N items |\n| `miqi memory list [--limit N] [--session S]` | Browse long-term snapshot entries |\n| `miqi memory delete ` | Remove a snapshot entry by ID |\n| `miqi memory lessons status` | Show self-improvement lesson stats |\n| `miqi memory lessons list` | List lessons (filter by `--scope`, `--session`, `--limit`) |\n| `miqi memory lessons enable ` | Re-enable a disabled lesson |\n| `miqi memory lessons disable ` | Suppress a lesson from future prompts |\n| `miqi memory lessons delete ` | Permanently remove a lesson |\n| `miqi memory lessons compact [--max-lessons N]` | Prune lessons to at most N entries |\n| `miqi memory lessons reset` | Wipe all lessons |\n\n**Session Management**\n\n| Command | Description |\n|---|---|\n| `miqi session compact --session ` | Compact a single conversation session |\n| `miqi session compact --all` | Compact all stored sessions |\n\n**Cron Scheduler**\n\n| Command | Description |\n|---|---|\n| `miqi cron list` | List all scheduled jobs |\n| `miqi cron add` | Add a new scheduled job |\n| `miqi cron run ` | Trigger a job manually |\n| `miqi cron enable ` | Enable a job |\n| `miqi cron disable ` | Disable a job |\n| `miqi cron remove ` | Remove a job permanently |\n\n**Configuration**\n\n| Command | Description |\n|---|---|\n| `miqi config show` | Print all non-default config values |\n| `miqi config provider ` | Set or update a provider's API key / base URL |\n| `miqi config feishu` | One-shot Feishu channel + feishu-mcp setup |\n| `miqi config pdf2zh` | Configure pdf2zh MCP server (auto-fills LLM credentials) |\n| `miqi config mcp list` | List all configured MCP servers |\n| `miqi config mcp add ` | Add or update an MCP server (stdio or HTTP) |\n| `miqi config mcp remove ` | Remove an MCP server |\n\n---\n\n## Core Capabilities\n\n### Memory & Self-Improvement\n\nMiQi uses a RAM-first memory architecture:\n\n- **Session window** β unconsolidated recent context for fast recall, persisted by default as append-only JSONL files under `/sessions/`\n- **Long-term snapshots** β periodic persistence with audit trails under `/memory/`\n- **Lesson extraction** β automatically distills insights from user feedback and tool outcomes\n- **Configurable confidence thresholds** β controls promotion of lessons to long-term memory\n\n### Agent Runtime Controls\n\n- **Iteration budget** β the main loop injects pressure hints as it approaches `maxToolIterations`\n- **Concurrent dispatch** β safe read-only or path-disjoint tool batches run via `asyncio.gather`\n- **Embedded hooks** β the `AgentLoop` constructor exposes optional smart-routing and context-compression controls for programmatic use\n\n### Scheduled Tasks\n\nJobs can be defined as:\n\n- **Interval jobs** β run every N seconds/minutes/hours\n- **Cron expression jobs** β full cron syntax support\n- **One-time jobs** β execute at a specific datetime\n\nAll jobs can be toggled, triggered manually, or removed via the CLI.\n\n### MCP Integration\n\nConnect any MCP-compatible tool server and expose its tools directly to the agent. Define MCP servers under `tools.mcpServers` in your config. For example, connect [feishu-mcp](https://github.com/lichman0405/feishu-mcp) to bring Feishu collaboration capabilities (messages, calendar, tasks, documents) into the agent via a clean MCP interface.\n\nFor long-running MCP tools (e.g. scientific computing), MiQi automatically sends periodic heartbeat progress messages to the user so they know the task is still running. Configure `progressIntervalSeconds` per MCP server (default 15s), increase `toolTimeout` for compute-heavy operations, and use `lazy` mode when a server exposes a large tool surface.\n\n### Task Queue Awareness\n\nWhen multiple users send messages simultaneously (e.g. in a group chat), MiQi queues tasks and notifies each user of their queue position. Users see when their task starts processing and how many tasks are ahead. This is enabled by default via `channels.sendQueueNotifications`.\n\n---\n\n## Development\n\n### Prerequisites\n\n- Python 3.11+\n- Linux or macOS (recommended)\n\n### Run Tests\n\n```bash\nPYTHONPATH=. .venv/bin/pytest -q\n```\n\n### Lint\n\n```bash\n.venv/bin/ruff check .\n```\n\n---\n\n## Migration Guide\n\nIf upgrading from a previous version or migrating from `nanobot`:\n\n| Item | Old | New |\n|---|---|---|\n| Python package | `nanobot.*` | `miqi.*` |\n| CLI command | `assistant` | `miqi` |\n| Runtime directory | `~/.assistant` | `~/.miqi` |\n| Workspace directory | `~/.assistant/workspace` | `~/.miqi/workspace` |\n\nBackward-compatible fallbacks for old config and data paths are retained where possible.\n\n---\n\n## MCP Ecosystem\n\nMiQi ships with seven domain-specific MCP servers as git submodules under `mcps/`.\nThey cover porous-material science, epitaxial surface analysis, PDF translation, and team collaboration.\n\n### Bundled MCP Servers\n\n| Name | Submodule | Python | Description |\n|---|---|---|---|\n| **zeopp** | `mcps/zeopp-backend` | 3.10+ | Zeo++ porous material geometry (volume, pore size, channels) |\n| **raspa2** | `mcps/raspa-mcp` | 3.11+ | RASPA2 molecular simulation β input templates, output parsing |\n| **mofstructure** | `mcps/mofstructure-mcp` | 3.9+ | MOF structural analysis β building blocks, topology, metal nodes |\n| **mofchecker** | `mcps/mofchecker-mcp` | **<3.11** | MOF structure validation β CIF integrity, geometry defects |\n| **miqrophi** | `mcps/miqrophi-mcp` | 3.10+ | Epitaxial lattice matching β CIF surface analysis, substrate screening, strain calculation |\n| **pdf2zh** | `mcps/pdftranslate-mcp` | 3.10β3.12 | PDF paper translation preserving LaTeX layout (needs OpenAI key) |\n| **feishu** | `mcps/feishu-mcp` | 3.11+ | Feishu/Lark β messaging, docs, tasks (needs App ID & Secret) |\n\n### Setup\n\n**1. Clone with submodules** (one-time):\n\n```bash\ngit clone --recurse-submodules https://github.com/lichman0405/miqi.git\n# or, if you already cloned without --recurse-submodules:\ngit submodule update --init --recursive\n```\n\n**2. Install Python venvs** for each MCP:\n\n```bash\nbash scripts/setup_mcps.sh\n```\n\nThe script uses [`uv`](https://docs.astral.sh/uv/) and pins the correct Python version per MCP\n(notably `mofchecker` requires Python 3.10; `pdf2zh` requires β€3.12).\n\n**3. Register MCPs with miqi**:\n\n```bash\nbash scripts/configure_mcps.sh\n```\n\nThis calls `miqi config mcp add` for every server with recommended timeouts and lazy-mode settings.\n\n**4. Add credentials** for the two servers that need them β open `~/.miqi/config.json` and fill in:\n\n```jsonc\n\"tools\": {\n \"mcpServers\": {\n \"pdf2zh\": {\n \"env\": {\n \"OPENAI_BASE_URL\": \"https://api.openai.com/v1\",\n \"OPENAI_API_KEY\": \"sk-...\",\n \"OPENAI_MODEL\": \"gpt-4o\"\n }\n },\n \"feishu\": {\n \"env\": {\n \"FEISHU_APP_ID\": \"cli_...\",\n \"FEISHU_APP_SECRET\": \"...\"\n }\n }\n }\n}\n```\n\n> **Security note**: MCP subprocesses launched via the stdio transport inherit only a minimal environment\n> (`HOME`, `PATH`, `SHELL`, `USER`, `TERM`, `LOGNAME`) β your LLM provider API keys are never exposed\n> to MCP servers unless you explicitly add them to `cfg.env` as shown above.\n\n---\n\n## Documentation Index\n\n### Root Documents\n\n- [README.md](README.md)\n- [CHANGELOG.md](CHANGELOG.md)\n- [CONTRIBUTING.md](CONTRIBUTING.md)\n\n### Project Docs (`docs/`)\n\n- [docs/index.md](docs/index.md)\n- [docs/getting-started.md](docs/getting-started.md)\n- [docs/configuration.md](docs/configuration.md)\n- [docs/cli-reference.md](docs/cli-reference.md)\n- [docs/mcp-integration.md](docs/mcp-integration.md)\n- [docs/architecture.md](docs/architecture.md)\n- [docs/memory-system.md](docs/memory-system.md)\n- [docs/self-improvement.md](docs/self-improvement.md)\n- [docs/security.md](docs/security.md)\n- [docs/developer-guide.md](docs/developer-guide.md)\n- [docs/changelog.md](docs/changelog.md)\n\n### Scripts (`scripts/`)\n\n- [scripts/setup_mcps.sh](scripts/setup_mcps.sh) β Create isolated Python venvs for all bundled MCP servers\n- [scripts/configure_mcps.sh](scripts/configure_mcps.sh) β Register all bundled MCPs into `~/.miqi/config.json`\n\n### Skills Docs (`miqi/skills/`)\n\n- [miqi/skills/README.md](miqi/skills/README.md)\n- [miqi/skills/cron/SKILL.md](miqi/skills/cron/SKILL.md)\n- [miqi/skills/feishu-report/SKILL.md](miqi/skills/feishu-report/SKILL.md)\n- [miqi/skills/github/SKILL.md](miqi/skills/github/SKILL.md)\n- [miqi/skills/memory/SKILL.md](miqi/skills/memory/SKILL.md)\n- [miqi/skills/paper-research/SKILL.md](miqi/skills/paper-research/SKILL.md)\n- [miqi/skills/skill-creator/SKILL.md](miqi/skills/skill-creator/SKILL.md)\n- [miqi/skills/summarize/SKILL.md](miqi/skills/summarize/SKILL.md)\n- [miqi/skills/tmux/SKILL.md](miqi/skills/tmux/SKILL.md)\n- [miqi/skills/weather/SKILL.md](miqi/skills/weather/SKILL.md)\n- [miqi/skills/workspace-cleanup/SKILL.md](miqi/skills/workspace-cleanup/SKILL.md)\n\n### Template Docs (`miqi/templates/`)\n\n- [miqi/templates/AGENTS.md](miqi/templates/AGENTS.md)\n- [miqi/templates/HEARTBEAT.md](miqi/templates/HEARTBEAT.md)\n- [miqi/templates/SOUL.md](miqi/templates/SOUL.md)\n- [miqi/templates/TOOLS.md](miqi/templates/TOOLS.md)\n- [miqi/templates/USER.md](miqi/templates/USER.md)\n- [miqi/templates/memory/MEMORY.md](miqi/templates/memory/MEMORY.md)\n\n---\n\n## License\n\n[MIT](LICENSE)\n"}, "f5cdfe5031a1dcef0a07eb9524d97eab882e8d85": {"t": 1785771691.2531707, "n": 20937, "h": "d70ab336ab5c5675", "c": "# MiQi\n\n\n πββ¬πͺΆ A lightweight, extensible personal AI agent framework for production automation and conversational workflows.\n
\n\n\n \n \n \n \n \n \n
\n\n---\n\n## Overview\n\nMiQi is a compact AI agent runtime designed for developers who want a self-hosted, programmable assistant. It connects to any OpenAI-compatible LLM provider and exposes a rich toolset β file operations, shell execution, web search, scheduled tasks, sub-agents, and external MCP servers β all configurable via a single JSON file.\n\nMiQi is a domain-focused evolution of the upstream [`nanobot`](https://github.com/HKUDS/nanobot) project. Full credit to the upstream team for the excellent engineering baseline in runtime design and tool abstraction.\n\n> **Reference baseline:** `nanobot` @ [`30361c9`](https://github.com/HKUDS/nanobot/commit/30361c9307f9014f49530d80abd5717bc97f554a) (2026-02-23)\n\n---\n\n## Features\n\n| Category | Capabilities |\n|---|---|\n| **LLM Providers** | OpenRouter, OpenAI, Anthropic, DeepSeek, Gemini, Groq, Moonshot, MiniMax, ZhipuAI, DashScope (Qwen), SiliconFlow, VolcEngine, AiHubMix, vLLM, Ollama, and any OpenAI-compatible endpoint |\n| **Built-in Tools** | File system, shell, web fetch/search, paper research (search/details/download), cron scheduler, sub-agent spawning |\n| **Channels** | Feishu is wired in the packaged gateway today; additional adapter modules for Telegram/Discord/Slack/Email/QQ/DingTalk/MoChat are present in the repository for extension work |\n| **MCP Integration** | Connect any MCP-compatible tool server (e.g. [feishu-mcp](https://github.com/lichman0405/feishu-mcp)) |\n| **Memory** | RAM-first long-term snapshots, lesson extraction, and append-only JSONL session history under the configured workspace |\n| **Agent Runtime** | Safe concurrent tool execution for read-only batches, iteration-budget safeguards, MCP heartbeat progress, and optional embedded routing/compression hooks |\n| **Extensibility** | MCP server integration, skill files, custom provider plugins |\n| **CLI** | Interactive onboarding, agent chat, gateway mode, cron and memory management |\n\n---\n\n## Quick Start\n\n### Installation\n\n#### Using [uv](https://docs.astral.sh/uv/) (Recommended)\n\n[uv](https://github.com/astral-sh/uv) is a fast Python package manager that uses the `uv.lock` lockfile shipped in this repository for reproducible installs.\n\n```bash\n# Install uv (skip if already installed)\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n# Verify uv\nuv --version # e.g. uv 0.11.x\n\n# Clone and install\ngit clone https://github.com/lichman0405/MiQi.git\ncd MiQi\nuv sync # creates .venv, installs locked dependencies + miqi\n\n# Activate the virtual environment\nsource .venv/bin/activate\n\n# Verify\nmiqi --version\n```\n\n#### Using pip\n\n```bash\ngit clone https://github.com/lichman0405/MiQi.git\ncd MiQi\n\npython3 -m venv .venv\nsource .venv/bin/activate\n\npip install --upgrade pip\npip install -e .\n\nmiqi --version\n```\n\n### First Run\n\n```bash\n# Interactive setup wizard β configures your provider, model, and identity\nmiqi onboard\n\n# Send a one-shot message\nmiqi agent -m \"hello\"\n\n# Start an interactive chat session\nmiqi agent\n\n# Launch the long-running gateway (channels + scheduled jobs)\nmiqi gateway\n```\n\n`miqi onboard` now also supports:\n\n- Paper research tool configuration (`tools.papers` provider, API key, limits)\n\n---\n\n## Installation Options\n\n### With Dev Dependencies\n\n```bash\n# uv (recommended) β installs pytest, ruff, pytest-asyncio\nuv sync --extra dev\n\n# pip alternative\npip install -e '.[dev]'\n```\n\n### Docker (Recommended for Production)\n\n```bash\n# Start the gateway\ndocker compose up --build miqi-gateway\n\n# Run a one-off CLI command in the container\ndocker compose --profile cli run --rm miqi-cli status\n```\n\n**Runtime data directory mapping:**\n\n| Location | Path |\n|---|---|\n| Host | `~/.miqi` |\n| Container | `/home/miqi/.miqi` |\n\n> **Security:** The container runs as unprivileged user `miqi` (UID 1000) β not root. The gateway port (`18790`) is bound to `127.0.0.1` by default and is **not** exposed to the network. Use a reverse proxy (e.g. Nginx) to expose it externally.\n\n### Bare-Metal (Non-Docker) Deployment\n\nFor running the gateway directly on a Linux/macOS host as a long-running service:\n\n**1. Prepare configuration** (if not done already):\n\n```bash\n# Interactive setup β creates ~/.miqi/config.json\nmiqi onboard\n\n# Verify the config\nmiqi status\n```\n\n**2. (Optional) Set up MCP servers:**\n\n```bash\nbash scripts/setup_mcps.sh # install isolated venvs\nbash scripts/configure_mcps.sh # register MCPs into config\n```\n\n**3. Run with systemd** (Linux, recommended):\n\nCreate `/etc/systemd/system/miqi.service`:\n\n```ini\n[Unit]\nDescription=MiQi AI Agent Gateway\nAfter=network.target\n\n[Service]\nType=simple\nUser=miqi\nWorkingDirectory=/home/miqi\nExecStart=/home/miqi/.local/bin/miqi gateway\nRestart=on-failure\nRestartSec=10\nEnvironment=HOME=/home/miqi\n\n[Install]\nWantedBy=multi-user.target\n```\n\n```bash\nsudo systemctl daemon-reload\nsudo systemctl enable --now miqi\nsudo journalctl -u miqi -f # tail logs\n```\n\nOn macOS, use `launchd` or a process manager like `supervisord` instead.\n\n**4. Reverse proxy** (optional, for external access):\n\nThe gateway listens on `127.0.0.1:18790`. To expose it, place it behind Nginx:\n\n```nginx\nserver {\n listen 443 ssl;\n server_name miqi.example.com;\n\n location / {\n proxy_pass http://127.0.0.1:18790;\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n }\n}\n```\n\n### Upgrading\n\n```bash\ncd MiQi\ngit pull --recurse-submodules\n\n# Reinstall core\nuv sync # or: pip install -e .\n\nbash scripts/setup_mcps.sh # update MCP venvs\nbash scripts/configure_mcps.sh # re-register MCPs (idempotent)\n# then restart the gateway (systemctl restart miqi / docker compose up --build)\n```\n\n> **Note:** The Docker image does **not** include MCP submodules β MCP servers run as separate stdio subprocesses on the host. When using Docker, mount or install MCP venvs on the host and configure `tools.mcpServers` commands to point at host-side interpreters, or run MCP servers as separate containers and use HTTP transport (`url` instead of `command`).\n\n---\n\n## Configuration\n\nMiQi reads from `~/.miqi/config.json`. The interactive wizard (`miqi onboard`) can generate this file for you.\n\n**Default paths:**\n\n| Item | Path |\n|---|---|\n| Config file | `~/.miqi/config.json` |\n| Workspace | `~/.miqi/workspace` |\n\n### Configuration Skeleton\n\n```json\n{\n \"providers\": {\n \"openrouter\": {\n \"apiKey\": \"sk-or-v1-xxx\"\n }\n },\n \"agents\": {\n \"defaults\": {\n \"model\": \"anthropic/claude-opus-4-5\",\n \"name\": \"miqi\",\n \"temperature\": 0.1\n }\n },\n \"channels\": {},\n \"tools\": {},\n \"heartbeat\": {\n \"enabled\": true,\n \"intervalSeconds\": 1800\n }\n}\n```\n\n### Key Sections\n\n- **`providers`** β API keys, custom `apiBase` URLs, and optional `extraHeaders` (for example `APP-Code` on AiHubMix) for each provider.\n- **`agents.defaults`** β Default model, temperature, `maxTokens`, `maxToolIterations`, `maxToolResultChars`, `contextLimitChars`, `memoryWindow`, and the workspace path.\n- **`agents.memory`** β Flush cadence plus in-memory short-term window sizing. Runtime files live under `/memory/`.\n- **`agents.sessions`** β JSONL session compaction thresholds and saved-tool-result truncation. The schema also exposes `useSqlite` for the shipped SQLite+FTS5 session backend module, but the packaged CLI/gateway path still instantiates the JSONL `SessionManager` by default.\n- **`agents.selfImprovement`** β Lesson extraction settings such as `maxLessonsInPrompt`, `minLessonConfidence`, `feedbackMaxMessageChars`, and promotion controls.\n- **`agents.smartRouting`** β Cheap-model routing settings. `AgentLoop` supports them programmatically; the packaged CLI/gateway path currently leaves this disabled unless you embed the runtime yourself.\n- **`agents.commandApproval`** β Schema for interactive dangerous-command approval. The repository ships the helper module, while the default `exec` tool path still relies on static deny-pattern guards.\n- **`channels`** β Global channel delivery flags (`sendProgress`, `sendToolHints`, `sendQueueNotifications`) plus Feishu gateway configuration. Other adapter modules exist in the repo but are not currently surfaced by the public config schema.\n- **`gateway`** β HTTP gateway listen address (`host`, `port`; default `0.0.0.0:18790` for bare-metal runs). Docker Compose binds the published port to `127.0.0.1:18790` by default.\n- **`tools`** β Web/search/fetch behavior, paper research provider settings, shell execution policy (`tools.exec.timeout`, `tools.exec.envPassthrough`), the global `restrictToWorkspace` flag, and MCP server definitions.\n - **`tools.mcpServers..progressIntervalSeconds`** β Heartbeat interval for long-running MCP tools. Set `0` to disable. Default `15`.\n - **`tools.mcpServers..toolTimeout`** β Timeout before a single MCP tool call is cancelled. Default `30`.\n - **`tools.mcpServers..lazy`** β Register one lightweight gateway tool instead of all server tools up front.\n - **`tools.mcpServers..description`** β LLM-facing description for lazy gateway mode.\n- **`heartbeat`** β Periodic background prompts (`enabled`, `intervalSeconds`) for proactive behaviors.\n- **`cron`** β Scheduler-wide job timeout (`jobTimeoutSeconds`; default `86400`).\n\n> **Security:** Config files are automatically saved with `0600` permissions (owner-read-only) to protect API keys. See [docs/security.md](docs/security.md) for the current security model and operational limits.\n\n### Environment Variable Overrides\n\nEvery config field can be overridden at runtime via environment variables using the prefix `MIQI_` and `__` as the nesting delimiter:\n\n```bash\n# Override the default model\nMIQI_AGENTS__DEFAULTS__MODEL=deepseek/deepseek-chat miqi agent\n\n# Inject an API key without editing config.json\nMIQI_PROVIDERS__OPENROUTER__API_KEY=sk-or-v1-xxx miqi gateway\n```\n\nThis is particularly useful in containerised deployments where secrets are injected as environment variables rather than mounted files.\n\n---\n\n## CLI Reference\n\n**Agent & Gateway**\n\n| Command | Description |\n|---|---|\n| `miqi onboard` | Interactive setup wizard |\n| `miqi agent` | Start an interactive chat session |\n| `miqi agent -m \"\"` | Send a single prompt and exit |\n| `miqi gateway` | Run the long-running gateway (channels + cron) |\n\n**Status & Diagnostics**\n\n| Command | Description |\n|---|---|\n| `miqi status` | Show runtime and provider status |\n| `miqi channels status` | Show channel connection status |\n\n**Memory Management**\n\n| Command | Description |\n|---|---|\n| `miqi memory status` | Show memory snapshot and stats |\n| `miqi memory flush` | Force-persist pending memory updates immediately |\n| `miqi memory compact [--max-items N]` | Prune long-term snapshot to at most N items |\n| `miqi memory list [--limit N] [--session S]` | Browse long-term snapshot entries |\n| `miqi memory delete ` | Remove a snapshot entry by ID |\n| `miqi memory lessons status` | Show self-improvement lesson stats |\n| `miqi memory lessons list` | List lessons (filter by `--scope`, `--session`, `--limit`) |\n| `miqi memory lessons enable ` | Re-enable a disabled lesson |\n| `miqi memory lessons disable ` | Suppress a lesson from future prompts |\n| `miqi memory lessons delete ` | Permanently remove a lesson |\n| `miqi memory lessons compact [--max-lessons N]` | Prune lessons to at most N entries |\n| `miqi memory lessons reset` | Wipe all lessons |\n\n**Session Management**\n\n| Command | Description |\n|---|---|\n| `miqi session compact --session ` | Compact a single conversation session |\n| `miqi session compact --all` | Compact all stored sessions |\n\n**Cron Scheduler**\n\n| Command | Description |\n|---|---|\n| `miqi cron list` | List all scheduled jobs |\n| `miqi cron add` | Add a new scheduled job |\n| `miqi cron run ` | Trigger a job manually |\n| `miqi cron enable ` | Enable a job |\n| `miqi cron disable ` | Disable a job |\n| `miqi cron remove ` | Remove a job permanently |\n\n**Configuration**\n\n| Command | Description |\n|---|---|\n| `miqi config show` | Print all non-default config values |\n| `miqi config provider ` | Set or update a provider's API key / base URL |\n| `miqi config feishu` | One-shot Feishu channel + feishu-mcp setup |\n| `miqi config pdf2zh` | Configure pdf2zh MCP server (auto-fills LLM credentials) |\n| `miqi config mcp list` | List all configured MCP servers |\n| `miqi config mcp add ` | Add or update an MCP server (stdio or HTTP) |\n| `miqi config mcp remove ` | Remove an MCP server |\n\n---\n\n## Core Capabilities\n\n### Memory & Self-Improvement\n\nMiQi uses a RAM-first memory architecture:\n\n- **Session window** β unconsolidated recent context for fast recall, persisted by default as append-only JSONL files under `/sessions/`\n- **Long-term snapshots** β periodic persistence with audit trails under `/memory/`\n- **Lesson extraction** β automatically distills insights from user feedback and tool outcomes\n- **Configurable confidence thresholds** β controls promotion of lessons to long-term memory\n\n### Agent Runtime Controls\n\n- **Iteration budget** β the main loop injects pressure hints as it approaches `maxToolIterations`\n- **Concurrent dispatch** β safe read-only or path-disjoint tool batches run via `asyncio.gather`\n- **Embedded hooks** β the `AgentLoop` constructor exposes optional smart-routing and context-compression controls for programmatic use\n\n### Scheduled Tasks\n\nJobs can be defined as:\n\n- **Interval jobs** β run every N seconds/minutes/hours\n- **Cron expression jobs** β full cron syntax support\n- **One-time jobs** β execute at a specific datetime\n\nAll jobs can be toggled, triggered manually, or removed via the CLI.\n\n### MCP Integration\n\nConnect any MCP-compatible tool server and expose its tools directly to the agent. Define MCP servers under `tools.mcpServers` in your config. For example, connect [feishu-mcp](https://github.com/lichman0405/feishu-mcp) to bring Feishu collaboration capabilities (messages, calendar, tasks, documents) into the agent via a clean MCP interface.\n\nFor long-running MCP tools (e.g. scientific computing), MiQi automatically sends periodic heartbeat progress messages to the user so they know the task is still running. Configure `progressIntervalSeconds` per MCP server (default 15s), increase `toolTimeout` for compute-heavy operations, and use `lazy` mode when a server exposes a large tool surface.\n\n### Task Queue Awareness\n\nWhen multiple users send messages simultaneously (e.g. in a group chat), MiQi queues tasks and notifies each user of their queue position. Users see when their task starts processing and how many tasks are ahead. This is enabled by default via `channels.sendQueueNotifications`.\n\n---\n\n## Development\n\n### Prerequisites\n\n- Python 3.11+\n- Linux or macOS (recommended)\n\n### Run Tests\n\n```bash\nPYTHONPATH=. .venv/bin/pytest -q\n```\n\n### Lint\n\n```bash\n.venv/bin/ruff check .\n```\n\n---\n\n## Migration Guide\n\nIf upgrading from a previous version or migrating from `nanobot`:\n\n| Item | Old | New |\n|---|---|---|\n| Python package | `nanobot.*` | `miqi.*` |\n| CLI command | `assistant` | `miqi` |\n| Runtime directory | `~/.assistant` | `~/.miqi` |\n| Workspace directory | `~/.assistant/workspace` | `~/.miqi/workspace` |\n\nBackward-compatible fallbacks for old config and data paths are retained where possible.\n\n---\n\n## MCP Ecosystem\n\nMiQi ships with seven domain-specific MCP servers as git submodules under `mcps/`.\nThey cover porous-material science, epitaxial surface analysis, PDF translation, and team collaboration.\n\n### Bundled MCP Servers\n\n| Name | Submodule | Python | Description |\n|---|---|---|---|\n| **zeopp** | `mcps/zeopp-backend` | 3.10+ | Zeo++ porous material geometry (volume, pore size, channels) |\n| **raspa2** | `mcps/raspa-mcp` | 3.11+ | RASPA2 molecular simulation β input templates, output parsing |\n| **mofstructure** | `mcps/mofstructure-mcp` | 3.9+ | MOF structural analysis β building blocks, topology, metal nodes |\n| **mofchecker** | `mcps/mofchecker-mcp` | **<3.11** | MOF structure validation β CIF integrity, geometry defects |\n| **miqrophi** | `mcps/miqrophi-mcp` | 3.10+ | Epitaxial lattice matching β CIF surface analysis, substrate screening, strain calculation |\n| **pdf2zh** | `mcps/pdftranslate-mcp` | 3.10β3.12 | PDF paper translation preserving LaTeX layout (needs OpenAI key) |\n| **feishu** | `mcps/feishu-mcp` | 3.11+ | Feishu/Lark β messaging, docs, tasks (needs App ID & Secret) |\n\n### Setup\n\n**1. Clone with submodules** (one-time):\n\n```bash\ngit clone --recurse-submodules https://github.com/lichman0405/miqi.git\n# or, if you already cloned without --recurse-submodules:\ngit submodule update --init --recursive\n```\n\n**2. Install Python venvs** for each MCP:\n\n```bash\nbash scripts/setup_mcps.sh\n```\n\nThe script uses [`uv`](https://docs.astral.sh/uv/) and pins the correct Python version per MCP\n(notably `mofchecker` requires Python 3.10; `pdf2zh` requires β€3.12).\n\n**3. Register MCPs with miqi**:\n\n```bash\nbash scripts/configure_mcps.sh\n```\n\nThis calls `miqi config mcp add` for every server with recommended timeouts and lazy-mode settings.\n\n**4. Add credentials** for the two servers that need them β open `~/.miqi/config.json` and fill in:\n\n```jsonc\n\"tools\": {\n \"mcpServers\": {\n \"pdf2zh\": {\n \"env\": {\n \"OPENAI_BASE_URL\": \"https://api.openai.com/v1\",\n \"OPENAI_API_KEY\": \"sk-...\",\n \"OPENAI_MODEL\": \"gpt-4o\"\n }\n },\n \"feishu\": {\n \"env\": {\n \"FEISHU_APP_ID\": \"cli_...\",\n \"FEISHU_APP_SECRET\": \"...\"\n }\n }\n }\n}\n```\n\n> **Security note**: MCP subprocesses launched via the stdio transport inherit only a minimal environment\n> (`HOME`, `PATH`, `SHELL`, `USER`, `TERM`, `LOGNAME`) β your LLM provider API keys are never exposed\n> to MCP servers unless you explicitly add them to `cfg.env` as shown above.\n\n---\n\n## Documentation Index\n\n### Root Documents\n\n- [README.md](README.md)\n- [CHANGELOG.md](CHANGELOG.md)\n- [CONTRIBUTING.md](CONTRIBUTING.md)\n\n### Project Docs (`docs/`)\n\n- [docs/index.md](docs/index.md)\n- [docs/getting-started.md](docs/getting-started.md)\n- [docs/configuration.md](docs/configuration.md)\n- [docs/cli-reference.md](docs/cli-reference.md)\n- [docs/mcp-integration.md](docs/mcp-integration.md)\n- [docs/architecture.md](docs/architecture.md)\n- [docs/memory-system.md](docs/memory-system.md)\n- [docs/self-improvement.md](docs/self-improvement.md)\n- [docs/security.md](docs/security.md)\n- [docs/developer-guide.md](docs/developer-guide.md)\n- [docs/changelog.md](docs/changelog.md)\n\n### Scripts (`scripts/`)\n\n- [scripts/setup_mcps.sh](scripts/setup_mcps.sh) β Create isolated Python venvs for all bundled MCP servers\n- [scripts/configure_mcps.sh](scripts/configure_mcps.sh) β Register all bundled MCPs into `~/.miqi/config.json`\n\n### Skills Docs (`miqi/skills/`)\n\n- [miqi/skills/README.md](miqi/skills/README.md)\n- [miqi/skills/cron/SKILL.md](miqi/skills/cron/SKILL.md)\n- [miqi/skills/feishu-report/SKILL.md](miqi/skills/feishu-report/SKILL.md)\n- [miqi/skills/github/SKILL.md](miqi/skills/github/SKILL.md)\n- [miqi/skills/memory/SKILL.md](miqi/skills/memory/SKILL.md)\n- [miqi/skills/paper-research/SKILL.md](miqi/skills/paper-research/SKILL.md)\n- [miqi/skills/skill-creator/SKILL.md](miqi/skills/skill-creator/SKILL.md)\n- [miqi/skills/summarize/SKILL.md](miqi/skills/summarize/SKILL.md)\n- [miqi/skills/tmux/SKILL.md](miqi/skills/tmux/SKILL.md)\n- [miqi/skills/weather/SKILL.md](miqi/skills/weather/SKILL.md)\n- [miqi/skills/workspace-cleanup/SKILL.md](miqi/skills/workspace-cleanup/SKILL.md)\n\n### Template Docs (`miqi/templates/`)\n\n- [miqi/templates/AGENTS.md](miqi/templates/AGENTS.md)\n- [miqi/templates/HEARTBEAT.md](miqi/templates/HEARTBEAT.md)\n- [miqi/templates/SOUL.md](miqi/templates/SOUL.md)\n- [miqi/templates/TOOLS.md](miqi/templates/TOOLS.md)\n- [miqi/templates/USER.md](miqi/templates/USER.md)\n- [miqi/templates/memory/MEMORY.md](miqi/templates/memory/MEMORY.md)\n\n---\n\n## License\n\n[MIT](LICENSE)\n"}, "c8af5a68eba8e4739dfe43eee8825240509bf001": {"t": 1785771693.4342408, "n": 21115, "h": "75603bef63c5993d", "c": "# MiQi\n\n\n πββ¬πͺΆ A lightweight, extensible personal AI agent framework for production automation and conversational workflows.\n
\n\n\n \n \n \n \n \n \n
\n\n---\n\n## Overview\n\nMiQi is a compact AI agent runtime designed for developers who want a self-hosted, programmable assistant. It connects to any OpenAI-compatible LLM provider and exposes a rich toolset β file operations, shell execution, web search, scheduled tasks, sub-agents, and external MCP servers β all configurable via a single JSON file.\n\nMiQi is a domain-focused evolution of the upstream [`nanobot`](https://github.com/HKUDS/nanobot) project. Full credit to the upstream team for the excellent engineering baseline in runtime design and tool abstraction.\n\n> **Reference baseline:** `nanobot` @ [`30361c9`](https://github.com/HKUDS/nanobot/commit/30361c9307f9014f49530d80abd5717bc97f554a) (2026-02-23)\n\n---\n\n## Features\n\n| Category | Capabilities |\n|---|---|\n| **LLM Providers** | OpenRouter, OpenAI, Anthropic, DeepSeek, Gemini, Groq, Moonshot, MiniMax, ZhipuAI, DashScope (Qwen), SiliconFlow, VolcEngine, AiHubMix, vLLM, Ollama, OpenAI Codex (OAuth), GitHub Copilot (OAuth), and any OpenAI-compatible endpoint |\n| **Built-in Tools** | File system, shell, web fetch/search, paper research (search/details/download), cron scheduler, sub-agent spawning |\n| **Channels** | Feishu is wired in the packaged gateway today; additional adapter modules for Telegram/Discord/Slack/Email/QQ/DingTalk/MoChat are present in the repository for extension work |\n| **MCP Integration** | Connect any MCP-compatible tool server (e.g. [feishu-mcp](https://github.com/lichman0405/feishu-mcp)) |\n| **Memory** | RAM-first long-term snapshots, lesson extraction, and append-only JSONL session history under the configured workspace |\n| **Agent Runtime** | Safe concurrent tool execution for read-only batches, iteration-budget safeguards, MCP heartbeat progress, and optional embedded routing/compression hooks |\n| **Extensibility** | MCP server integration, skill files, custom provider plugins |\n| **CLI** | Interactive onboarding, agent chat, gateway mode, cron and memory management |\n\n---\n\n## Quick Start\n\n### Installation\n\n#### Using [uv](https://docs.astral.sh/uv/) (Recommended)\n\n[uv](https://github.com/astral-sh/uv) is a fast Python package manager that uses the `uv.lock` lockfile shipped in this repository for reproducible installs.\n\n```bash\n# Install uv (skip if already installed)\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n# Verify uv\nuv --version # e.g. uv 0.11.x\n\n# Clone and install\ngit clone https://github.com/lichman0405/MiQi.git\ncd MiQi\nuv sync # creates .venv, installs locked dependencies + miqi\n\n# Activate the virtual environment\nsource .venv/bin/activate\n\n# Verify\nmiqi --version\n```\n\n#### Using pip\n\n```bash\ngit clone https://github.com/lichman0405/MiQi.git\ncd MiQi\n\npython3 -m venv .venv\nsource .venv/bin/activate\n\npip install --upgrade pip\npip install -e .\n\nmiqi --version\n```\n\n### First Run\n\n```bash\n# Interactive setup wizard β configures your provider, model, and identity\nmiqi onboard\n\n# Send a one-shot message\nmiqi agent -m \"hello\"\n\n# Start an interactive chat session\nmiqi agent\n\n# Launch the long-running gateway (channels + scheduled jobs)\nmiqi gateway\n```\n\n`miqi onboard` now also supports:\n\n- Paper research tool configuration (`tools.papers` provider, API key, limits)\n\n---\n\n## Installation Options\n\n### With Dev Dependencies\n\n```bash\n# uv (recommended) β installs pytest, ruff, pytest-asyncio\nuv sync --extra dev\n\n# pip alternative\npip install -e '.[dev]'\n```\n\n### Docker (Recommended for Production)\n\n```bash\n# Start the gateway\ndocker compose up --build miqi-gateway\n\n# Run a one-off CLI command in the container\ndocker compose --profile cli run --rm miqi-cli status\n```\n\n**Runtime data directory mapping:**\n\n| Location | Path |\n|---|---|\n| Host | `~/.miqi` |\n| Container | `/home/miqi/.miqi` |\n\n> **Security:** The container runs as unprivileged user `miqi` (UID 1000) β not root. The gateway port (`18790`) is bound to `127.0.0.1` by default and is **not** exposed to the network. Use a reverse proxy (e.g. Nginx) to expose it externally.\n\n### Bare-Metal (Non-Docker) Deployment\n\nFor running the gateway directly on a Linux/macOS host as a long-running service:\n\n**1. Prepare configuration** (if not done already):\n\n```bash\n# Interactive setup β creates ~/.miqi/config.json\nmiqi onboard\n\n# Verify the config\nmiqi status\n```\n\n**2. (Optional) Set up MCP servers:**\n\n```bash\nbash scripts/setup_mcps.sh # install isolated venvs\nbash scripts/configure_mcps.sh # register MCPs into config\n```\n\n**3. Run with systemd** (Linux, recommended):\n\nCreate `/etc/systemd/system/miqi.service`:\n\n```ini\n[Unit]\nDescription=MiQi AI Agent Gateway\nAfter=network.target\n\n[Service]\nType=simple\nUser=miqi\nWorkingDirectory=/home/miqi\nExecStart=/home/miqi/.local/bin/miqi gateway\nRestart=on-failure\nRestartSec=10\nEnvironment=HOME=/home/miqi\n\n[Install]\nWantedBy=multi-user.target\n```\n\n```bash\nsudo systemctl daemon-reload\nsudo systemctl enable --now miqi\nsudo journalctl -u miqi -f # tail logs\n```\n\nOn macOS, use `launchd` or a process manager like `supervisord` instead.\n\n**4. Reverse proxy** (optional, for external access):\n\nThe gateway listens on `127.0.0.1:18790`. To expose it, place it behind Nginx:\n\n```nginx\nserver {\n listen 443 ssl;\n server_name miqi.example.com;\n\n location / {\n proxy_pass http://127.0.0.1:18790;\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n }\n}\n```\n\n### Upgrading\n\n```bash\ncd MiQi\ngit pull --recurse-submodules\n\n# Reinstall core\nuv sync # or: pip install -e .\n\nbash scripts/setup_mcps.sh # update MCP venvs\nbash scripts/configure_mcps.sh # re-register MCPs (idempotent)\n# then restart the gateway (systemctl restart miqi / docker compose up --build)\n```\n\n> **Note:** The Docker image does **not** include MCP submodules β MCP servers run as separate stdio subprocesses on the host. When using Docker, mount or install MCP venvs on the host and configure `tools.mcpServers` commands to point at host-side interpreters, or run MCP servers as separate containers and use HTTP transport (`url` instead of `command`).\n\n---\n\n## Configuration\n\nMiQi reads from `~/.miqi/config.json`. The interactive wizard (`miqi onboard`) can generate this file for you.\n\n**Default paths:**\n\n| Item | Path |\n|---|---|\n| Config file | `~/.miqi/config.json` |\n| Workspace | `~/.miqi/workspace` |\n\n### Configuration Skeleton\n\n```json\n{\n \"providers\": {\n \"openrouter\": {\n \"apiKey\": \"sk-or-v1-xxx\"\n }\n },\n \"agents\": {\n \"defaults\": {\n \"model\": \"anthropic/claude-opus-4-5\",\n \"name\": \"miqi\",\n \"temperature\": 0.1\n }\n },\n \"channels\": {},\n \"tools\": {},\n \"heartbeat\": {\n \"enabled\": true,\n \"intervalSeconds\": 1800\n }\n}\n```\n\n### Key Sections\n\n- **`providers`** β API keys, custom `apiBase` URLs, and optional `extraHeaders` (for example `APP-Code` on AiHubMix) for each provider.\n- **`agents.defaults`** β Default model, temperature, `maxTokens`, `maxToolIterations`, `maxToolResultChars`, `contextLimitChars`, `memoryWindow`, and the workspace path.\n- **`agents.memory`** β Flush cadence plus in-memory short-term window sizing. Runtime files live under `/memory/`.\n- **`agents.sessions`** β JSONL session compaction thresholds and saved-tool-result truncation. The schema also exposes `useSqlite` for the shipped SQLite+FTS5 session backend module, but the packaged CLI/gateway path still instantiates the JSONL `SessionManager` by default.\n- **`agents.selfImprovement`** β Lesson extraction settings such as `maxLessonsInPrompt`, `minLessonConfidence`, `feedbackMaxMessageChars`, and promotion controls.\n- **`agents.smartRouting`** β Cheap-model routing settings. `AgentLoop` supports them programmatically; the packaged CLI/gateway path currently leaves this disabled unless you embed the runtime yourself.\n- **`agents.commandApproval`** β Schema for interactive dangerous-command approval. The repository ships the helper module, while the default `exec` tool path still relies on static deny-pattern guards.\n- **`channels`** β Global channel delivery flags (`sendProgress`, `sendToolHints`, `sendQueueNotifications`) plus Feishu gateway configuration. Other adapter modules exist in the repo but are not currently surfaced by the public config schema.\n- **`gateway`** β HTTP gateway listen address (`host`, `port`; default `0.0.0.0:18790` for bare-metal runs). Docker Compose binds the published port to `127.0.0.1:18790` by default.\n- **`tools`** β Web/search/fetch behavior, paper research provider settings, shell execution policy (`tools.exec.timeout`, `tools.exec.envPassthrough`), the global `restrictToWorkspace` flag, and MCP server definitions.\n - **`tools.mcpServers..progressIntervalSeconds`** β Heartbeat interval for long-running MCP tools. Set `0` to disable. Default `15`.\n - **`tools.mcpServers..toolTimeout`** β Timeout before a single MCP tool call is cancelled. Default `30`.\n - **`tools.mcpServers..lazy`** β Register one lightweight gateway tool instead of all server tools up front.\n - **`tools.mcpServers..description`** β LLM-facing description for lazy gateway mode.\n- **`heartbeat`** β Periodic background prompts (`enabled`, `intervalSeconds`) for proactive behaviors.\n- **`cron`** β Scheduler-wide job timeout (`jobTimeoutSeconds`; default `86400`).\n\n> **Security:** Config files are automatically saved with `0600` permissions (owner-read-only) to protect API keys. See [docs/security.md](docs/security.md) for the current security model and operational limits.\n\n### Environment Variable Overrides\n\nEvery config field can be overridden at runtime via environment variables using the prefix `MIQI_` and `__` as the nesting delimiter:\n\n```bash\n# Override the default model\nMIQI_AGENTS__DEFAULTS__MODEL=deepseek/deepseek-chat miqi agent\n\n# Inject an API key without editing config.json\nMIQI_PROVIDERS__OPENROUTER__API_KEY=sk-or-v1-xxx miqi gateway\n```\n\nThis is particularly useful in containerised deployments where secrets are injected as environment variables rather than mounted files.\n\n---\n\n## CLI Reference\n\n**Agent & Gateway**\n\n| Command | Description |\n|---|---|\n| `miqi onboard` | Interactive setup wizard |\n| `miqi agent` | Start an interactive chat session |\n| `miqi agent -m \"\"` | Send a single prompt and exit |\n| `miqi gateway` | Run the long-running gateway (channels + cron) |\n\n**Status & Diagnostics**\n\n| Command | Description |\n|---|---|\n| `miqi status` | Show runtime and provider status |\n| `miqi channels status` | Show channel connection status |\n\n**Memory Management**\n\n| Command | Description |\n|---|---|\n| `miqi memory status` | Show memory snapshot and stats |\n| `miqi memory flush` | Force-persist pending memory updates immediately |\n| `miqi memory compact [--max-items N]` | Prune long-term snapshot to at most N items |\n| `miqi memory list [--limit N] [--session S]` | Browse long-term snapshot entries |\n| `miqi memory delete ` | Remove a snapshot entry by ID |\n| `miqi memory lessons status` | Show self-improvement lesson stats |\n| `miqi memory lessons list` | List lessons (filter by `--scope`, `--session`, `--limit`) |\n| `miqi memory lessons enable ` | Re-enable a disabled lesson |\n| `miqi memory lessons disable ` | Suppress a lesson from future prompts |\n| `miqi memory lessons delete ` | Permanently remove a lesson |\n| `miqi memory lessons compact [--max-lessons N]` | Prune lessons to at most N entries |\n| `miqi memory lessons reset` | Wipe all lessons |\n\n**Session Management**\n\n| Command | Description |\n|---|---|\n| `miqi session compact --session ` | Compact a single conversation session |\n| `miqi session compact --all` | Compact all stored sessions |\n\n**Cron Scheduler**\n\n| Command | Description |\n|---|---|\n| `miqi cron list` | List all scheduled jobs |\n| `miqi cron add` | Add a new scheduled job |\n| `miqi cron run ` | Trigger a job manually |\n| `miqi cron enable ` | Enable a job |\n| `miqi cron disable ` | Disable a job |\n| `miqi cron remove ` | Remove a job permanently |\n\n**Configuration**\n\n| Command | Description |\n|---|---|\n| `miqi config show` | Print all non-default config values |\n| `miqi config provider ` | Set or update a provider's API key / base URL |\n| `miqi config feishu` | One-shot Feishu channel + feishu-mcp setup |\n| `miqi config pdf2zh` | Configure pdf2zh MCP server (auto-fills LLM credentials) |\n| `miqi config mcp list` | List all configured MCP servers |\n| `miqi config mcp add ` | Add or update an MCP server (stdio or HTTP) |\n| `miqi config mcp remove ` | Remove an MCP server |\n\n**Providers**\n\n| Command | Description |\n|---|---|\n| `miqi provider login openai-codex` | Authenticate with OpenAI Codex (OAuth) |\n\n---\n\n## Core Capabilities\n\n### Memory & Self-Improvement\n\nMiQi uses a RAM-first memory architecture:\n\n- **Session window** β unconsolidated recent context for fast recall, persisted by default as append-only JSONL files under `/sessions/`\n- **Long-term snapshots** β periodic persistence with audit trails under `/memory/`\n- **Lesson extraction** β automatically distills insights from user feedback and tool outcomes\n- **Configurable confidence thresholds** β controls promotion of lessons to long-term memory\n\n### Agent Runtime Controls\n\n- **Iteration budget** β the main loop injects pressure hints as it approaches `maxToolIterations`\n- **Concurrent dispatch** β safe read-only or path-disjoint tool batches run via `asyncio.gather`\n- **Embedded hooks** β the `AgentLoop` constructor exposes optional smart-routing and context-compression controls for programmatic use\n\n### Scheduled Tasks\n\nJobs can be defined as:\n\n- **Interval jobs** β run every N seconds/minutes/hours\n- **Cron expression jobs** β full cron syntax support\n- **One-time jobs** β execute at a specific datetime\n\nAll jobs can be toggled, triggered manually, or removed via the CLI.\n\n### MCP Integration\n\nConnect any MCP-compatible tool server and expose its tools directly to the agent. Define MCP servers under `tools.mcpServers` in your config. For example, connect [feishu-mcp](https://github.com/lichman0405/feishu-mcp) to bring Feishu collaboration capabilities (messages, calendar, tasks, documents) into the agent via a clean MCP interface.\n\nFor long-running MCP tools (e.g. scientific computing), MiQi automatically sends periodic heartbeat progress messages to the user so they know the task is still running. Configure `progressIntervalSeconds` per MCP server (default 15s), increase `toolTimeout` for compute-heavy operations, and use `lazy` mode when a server exposes a large tool surface.\n\n### Task Queue Awareness\n\nWhen multiple users send messages simultaneously (e.g. in a group chat), MiQi queues tasks and notifies each user of their queue position. Users see when their task starts processing and how many tasks are ahead. This is enabled by default via `channels.sendQueueNotifications`.\n\n---\n\n## Development\n\n### Prerequisites\n\n- Python 3.11+\n- Linux or macOS (recommended)\n\n### Run Tests\n\n```bash\nPYTHONPATH=. .venv/bin/pytest -q\n```\n\n### Lint\n\n```bash\n.venv/bin/ruff check .\n```\n\n---\n\n## Migration Guide\n\nIf upgrading from a previous version or migrating from `nanobot`:\n\n| Item | Old | New |\n|---|---|---|\n| Python package | `nanobot.*` | `miqi.*` |\n| CLI command | `assistant` | `miqi` |\n| Runtime directory | `~/.assistant` | `~/.miqi` |\n| Workspace directory | `~/.assistant/workspace` | `~/.miqi/workspace` |\n\nBackward-compatible fallbacks for old config and data paths are retained where possible.\n\n---\n\n## MCP Ecosystem\n\nMiQi ships with seven domain-specific MCP servers as git submodules under `mcps/`.\nThey cover porous-material science, epitaxial surface analysis, PDF translation, and team collaboration.\n\n### Bundled MCP Servers\n\n| Name | Submodule | Python | Description |\n|---|---|---|---|\n| **zeopp** | `mcps/zeopp-backend` | 3.10+ | Zeo++ porous material geometry (volume, pore size, channels) |\n| **raspa2** | `mcps/raspa-mcp` | 3.11+ | RASPA2 molecular simulation β input templates, output parsing |\n| **mofstructure** | `mcps/mofstructure-mcp` | 3.9+ | MOF structural analysis β building blocks, topology, metal nodes |\n| **mofchecker** | `mcps/mofchecker-mcp` | **<3.11** | MOF structure validation β CIF integrity, geometry defects |\n| **miqrophi** | `mcps/miqrophi-mcp` | 3.10+ | Epitaxial lattice matching β CIF surface analysis, substrate screening, strain calculation |\n| **pdf2zh** | `mcps/pdftranslate-mcp` | 3.10β3.12 | PDF paper translation preserving LaTeX layout (needs OpenAI key) |\n| **feishu** | `mcps/feishu-mcp` | 3.11+ | Feishu/Lark β messaging, docs, tasks (needs App ID & Secret) |\n\n### Setup\n\n**1. Clone with submodules** (one-time):\n\n```bash\ngit clone --recurse-submodules https://github.com/lichman0405/miqi.git\n# or, if you already cloned without --recurse-submodules:\ngit submodule update --init --recursive\n```\n\n**2. Install Python venvs** for each MCP:\n\n```bash\nbash scripts/setup_mcps.sh\n```\n\nThe script uses [`uv`](https://docs.astral.sh/uv/) and pins the correct Python version per MCP\n(notably `mofchecker` requires Python 3.10; `pdf2zh` requires β€3.12).\n\n**3. Register MCPs with miqi**:\n\n```bash\nbash scripts/configure_mcps.sh\n```\n\nThis calls `miqi config mcp add` for every server with recommended timeouts and lazy-mode settings.\n\n**4. Add credentials** for the two servers that need them β open `~/.miqi/config.json` and fill in:\n\n```jsonc\n\"tools\": {\n \"mcpServers\": {\n \"pdf2zh\": {\n \"env\": {\n \"OPENAI_BASE_URL\": \"https://api.openai.com/v1\",\n \"OPENAI_API_KEY\": \"sk-...\",\n \"OPENAI_MODEL\": \"gpt-4o\"\n }\n },\n \"feishu\": {\n \"env\": {\n \"FEISHU_APP_ID\": \"cli_...\",\n \"FEISHU_APP_SECRET\": \"...\"\n }\n }\n }\n}\n```\n\n> **Security note**: MCP subprocesses launched via the stdio transport inherit only a minimal environment\n> (`HOME`, `PATH`, `SHELL`, `USER`, `TERM`, `LOGNAME`) β your LLM provider API keys are never exposed\n> to MCP servers unless you explicitly add them to `cfg.env` as shown above.\n\n---\n\n## Documentation Index\n\n### Root Documents\n\n- [README.md](README.md)\n- [CHANGELOG.md](CHANGELOG.md)\n- [CONTRIBUTING.md](CONTRIBUTING.md)\n\n### Project Docs (`docs/`)\n\n- [docs/index.md](docs/index.md)\n- [docs/getting-started.md](docs/getting-started.md)\n- [docs/configuration.md](docs/configuration.md)\n- [docs/cli-reference.md](docs/cli-reference.md)\n- [docs/mcp-integration.md](docs/mcp-integration.md)\n- [docs/architecture.md](docs/architecture.md)\n- [docs/memory-system.md](docs/memory-system.md)\n- [docs/self-improvement.md](docs/self-improvement.md)\n- [docs/security.md](docs/security.md)\n- [docs/developer-guide.md](docs/developer-guide.md)\n- [docs/changelog.md](docs/changelog.md)\n\n### Scripts (`scripts/`)\n\n- [scripts/setup_mcps.sh](scripts/setup_mcps.sh) β Create isolated Python venvs for all bundled MCP servers\n- [scripts/configure_mcps.sh](scripts/configure_mcps.sh) β Register all bundled MCPs into `~/.miqi/config.json`\n\n### Skills Docs (`miqi/skills/`)\n\n- [miqi/skills/README.md](miqi/skills/README.md)\n- [miqi/skills/cron/SKILL.md](miqi/skills/cron/SKILL.md)\n- [miqi/skills/feishu-report/SKILL.md](miqi/skills/feishu-report/SKILL.md)\n- [miqi/skills/github/SKILL.md](miqi/skills/github/SKILL.md)\n- [miqi/skills/memory/SKILL.md](miqi/skills/memory/SKILL.md)\n- [miqi/skills/paper-research/SKILL.md](miqi/skills/paper-research/SKILL.md)\n- [miqi/skills/skill-creator/SKILL.md](miqi/skills/skill-creator/SKILL.md)\n- [miqi/skills/summarize/SKILL.md](miqi/skills/summarize/SKILL.md)\n- [miqi/skills/tmux/SKILL.md](miqi/skills/tmux/SKILL.md)\n- [miqi/skills/weather/SKILL.md](miqi/skills/weather/SKILL.md)\n- [miqi/skills/workspace-cleanup/SKILL.md](miqi/skills/workspace-cleanup/SKILL.md)\n\n### Template Docs (`miqi/templates/`)\n\n- [miqi/templates/AGENTS.md](miqi/templates/AGENTS.md)\n- [miqi/templates/HEARTBEAT.md](miqi/templates/HEARTBEAT.md)\n- [miqi/templates/SOUL.md](miqi/templates/SOUL.md)\n- [miqi/templates/TOOLS.md](miqi/templates/TOOLS.md)\n- [miqi/templates/USER.md](miqi/templates/USER.md)\n- [miqi/templates/memory/MEMORY.md](miqi/templates/memory/MEMORY.md)\n\n---\n\n## License\n\n[MIT](LICENSE)\n"}, "ca85f1037d497fa32404aea603c35a0374356d83": {"t": 1785771695.1140718, "n": 20440, "h": "4a4005814b79aea5", "c": "# MiQi\n\n\n πββ¬πͺΆ A lightweight, extensible personal AI agent framework for production automation and conversational workflows.\n
\n\n\n \n \n \n \n \n \n
\n\n---\n\n## Overview\n\nMiQi is a compact AI agent runtime designed for developers who want a self-hosted, programmable assistant. It connects to any OpenAI-compatible LLM provider and exposes a rich toolset β file operations, shell execution, web search, scheduled tasks, sub-agents, and external MCP servers β all configurable via a single JSON file.\n\nMiQi is a domain-focused evolution of the upstream [`nanobot`](https://github.com/HKUDS/nanobot) project. Full credit to the upstream team for the excellent engineering baseline in runtime design and tool abstraction.\n\n> **Reference baseline:** `nanobot` @ [`30361c9`](https://github.com/HKUDS/nanobot/commit/30361c9307f9014f49530d80abd5717bc97f554a) (2026-02-23)\n\n---\n\n## Features\n\n| Category | Capabilities |\n|---|---|\n| **LLM Providers** | OpenRouter, OpenAI, Anthropic, DeepSeek, Gemini, Groq, Moonshot, MiniMax, ZhipuAI, DashScope (Qwen), SiliconFlow, VolcEngine, AiHubMix, vLLM, Ollama, OpenAI Codex (OAuth), and any OpenAI-compatible endpoint |\n| **Built-in Tools** | File system, shell, web fetch/search, paper research (search/details/download), cron scheduler, sub-agent spawning |\n| **Channels** | Feishu is wired in the packaged gateway today; additional adapter modules for Telegram/Discord/Slack/Email/QQ/DingTalk/MoChat are present in the repository for extension work |\n| **MCP Integration** | Connect any MCP-compatible tool server (e.g. [feishu-mcp](https://github.com/lichman0405/feishu-mcp)) |\n| **Memory** | RAM-first long-term snapshots, lesson extraction, and append-only JSONL session history under the configured workspace |\n| **Agent Runtime** | Safe concurrent tool execution for read-only batches, iteration-budget safeguards, MCP heartbeat progress, and optional embedded routing/compression hooks |\n| **Extensibility** | MCP server integration, skill files, custom provider plugins |\n| **CLI** | Interactive onboarding, agent chat, gateway mode, cron and memory management |\n\n---\n\n## Quick Start\n\n### Installation\n\n```bash\n# Clone the repository\ngit clone https://github.com/lichman0405/miqi.git\ncd miqi\n\n# Create and activate a virtual environment\npython3 -m venv .venv\nsource .venv/bin/activate\n\n# Install MiQi\npip install --upgrade pip\npip install -e .\n\n# Verify\nmiqi --version\n```\n\n### First Run\n\n```bash\n# Interactive setup wizard β configures your provider, model, and identity\nmiqi onboard\n\n# Send a one-shot message\nmiqi agent -m \"hello\"\n\n# Start an interactive chat session\nmiqi agent\n\n# Launch the long-running gateway (channels + scheduled jobs)\nmiqi gateway\n```\n\n`miqi onboard` now also supports:\n\n- Paper research tool configuration (`tools.papers` provider, API key, limits)\n\n---\n\n## Installation Options\n\n### With Dev Dependencies\n\n```bash\npip install -e '.[dev]'\n```\n\n### Docker (Recommended for Production)\n\n```bash\n# Start the gateway\ndocker compose up --build miqi-gateway\n\n# Run a one-off CLI command in the container\ndocker compose --profile cli run --rm miqi-cli status\n```\n\n**Runtime data directory mapping:**\n\n| Location | Path |\n|---|---|\n| Host | `~/.miqi` |\n| Container | `/home/miqi/.miqi` |\n\n> **Security:** The container runs as unprivileged user `miqi` (UID 1000) β not root. The gateway port (`18790`) is bound to `127.0.0.1` by default and is **not** exposed to the network. Use a reverse proxy (e.g. Nginx) to expose it externally.\n\n### Bare-Metal (Non-Docker) Deployment\n\nFor running the gateway directly on a Linux/macOS host as a long-running service:\n\n**1. Prepare configuration** (if not done already):\n\n```bash\n# Interactive setup β creates ~/.miqi/config.json\nmiqi onboard\n\n# Verify the config\nmiqi status\n```\n\n**2. (Optional) Set up MCP servers:**\n\n```bash\nbash scripts/setup_mcps.sh # install isolated venvs\nbash scripts/configure_mcps.sh # register MCPs into config\n```\n\n**3. Run with systemd** (Linux, recommended):\n\nCreate `/etc/systemd/system/miqi.service`:\n\n```ini\n[Unit]\nDescription=MiQi AI Agent Gateway\nAfter=network.target\n\n[Service]\nType=simple\nUser=miqi\nWorkingDirectory=/home/miqi\nExecStart=/home/miqi/.local/bin/miqi gateway\nRestart=on-failure\nRestartSec=10\nEnvironment=HOME=/home/miqi\n\n[Install]\nWantedBy=multi-user.target\n```\n\n```bash\nsudo systemctl daemon-reload\nsudo systemctl enable --now miqi\nsudo journalctl -u miqi -f # tail logs\n```\n\nOn macOS, use `launchd` or a process manager like `supervisord` instead.\n\n**4. Reverse proxy** (optional, for external access):\n\nThe gateway listens on `127.0.0.1:18790`. To expose it, place it behind Nginx:\n\n```nginx\nserver {\n listen 443 ssl;\n server_name miqi.example.com;\n\n location / {\n proxy_pass http://127.0.0.1:18790;\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n }\n}\n```\n\n### Upgrading\n\n```bash\ncd miqi\ngit pull --recurse-submodules\npip install -e . # reinstall core\nbash scripts/setup_mcps.sh # update MCP venvs\nbash scripts/configure_mcps.sh # re-register MCPs (idempotent)\n# then restart the gateway (systemctl restart miqi / docker compose up --build)\n```\n\n> **Note:** The Docker image does **not** include MCP submodules β MCP servers run as separate stdio subprocesses on the host. When using Docker, mount or install MCP venvs on the host and configure `tools.mcpServers` commands to point at host-side interpreters, or run MCP servers as separate containers and use HTTP transport (`url` instead of `command`).\n\n---\n\n## Configuration\n\nMiQi reads from `~/.miqi/config.json`. The interactive wizard (`miqi onboard`) can generate this file for you.\n\n**Default paths:**\n\n| Item | Path |\n|---|---|\n| Config file | `~/.miqi/config.json` |\n| Workspace | `~/.miqi/workspace` |\n\n### Configuration Skeleton\n\n```json\n{\n \"providers\": {\n \"openrouter\": {\n \"apiKey\": \"sk-or-v1-xxx\"\n }\n },\n \"agents\": {\n \"defaults\": {\n \"model\": \"anthropic/claude-opus-4-5\",\n \"name\": \"miqi\",\n \"temperature\": 0.1\n }\n },\n \"channels\": {},\n \"tools\": {},\n \"heartbeat\": {\n \"enabled\": true,\n \"intervalSeconds\": 1800\n }\n}\n```\n\n### Key Sections\n\n- **`providers`** β API keys, custom `apiBase` URLs, and optional `extraHeaders` (for example `APP-Code` on AiHubMix) for each provider.\n- **`agents.defaults`** β Default model, temperature, `maxTokens`, `maxToolIterations`, `maxToolResultChars`, `contextLimitChars`, `memoryWindow`, and the workspace path.\n- **`agents.memory`** β Flush cadence plus in-memory short-term window sizing. Runtime files live under `/memory/`.\n- **`agents.sessions`** β JSONL session compaction thresholds and saved-tool-result truncation. The schema also exposes `useSqlite` for the shipped SQLite+FTS5 session backend module, but the packaged CLI/gateway path still instantiates the JSONL `SessionManager` by default.\n- **`agents.selfImprovement`** β Lesson extraction settings such as `maxLessonsInPrompt`, `minLessonConfidence`, `feedbackMaxMessageChars`, and promotion controls.\n- **`agents.smartRouting`** β Cheap-model routing settings. `AgentLoop` supports them programmatically; the packaged CLI/gateway path currently leaves this disabled unless you embed the runtime yourself.\n- **`agents.commandApproval`** β Schema for interactive dangerous-command approval. The repository ships the helper module, while the default `exec` tool path still relies on static deny-pattern guards.\n- **`channels`** β Global channel delivery flags (`sendProgress`, `sendToolHints`, `sendQueueNotifications`) plus Feishu gateway configuration. Other adapter modules exist in the repo but are not currently surfaced by the public config schema.\n- **`gateway`** β HTTP gateway listen address (`host`, `port`; default `0.0.0.0:18790` for bare-metal runs). Docker Compose binds the published port to `127.0.0.1:18790` by default.\n- **`tools`** β Web/search/fetch behavior, paper research provider settings, shell execution policy (`tools.exec.timeout`, `tools.exec.envPassthrough`), the global `restrictToWorkspace` flag, and MCP server definitions.\n - **`tools.mcpServers..progressIntervalSeconds`** β Heartbeat interval for long-running MCP tools. Set `0` to disable. Default `15`.\n - **`tools.mcpServers..toolTimeout`** β Timeout before a single MCP tool call is cancelled. Default `30`.\n - **`tools.mcpServers..lazy`** β Register one lightweight gateway tool instead of all server tools up front.\n - **`tools.mcpServers..description`** β LLM-facing description for lazy gateway mode.\n- **`heartbeat`** β Periodic background prompts (`enabled`, `intervalSeconds`) for proactive behaviors.\n- **`cron`** β Scheduler-wide job timeout (`jobTimeoutSeconds`; default `86400`).\n\n> **Security:** Config files are automatically saved with `0600` permissions (owner-read-only) to protect API keys. See [docs/security.md](docs/security.md) for the current security model and operational limits.\n\n### Environment Variable Overrides\n\nEvery config field can be overridden at runtime via environment variables using the prefix `MIQI_` and `__` as the nesting delimiter:\n\n```bash\n# Override the default model\nMIQI_AGENTS__DEFAULTS__MODEL=deepseek/deepseek-chat miqi agent\n\n# Inject an API key without editing config.json\nMIQI_PROVIDERS__OPENROUTER__API_KEY=sk-or-v1-xxx miqi gateway\n```\n\nThis is particularly useful in containerised deployments where secrets are injected as environment variables rather than mounted files.\n\n---\n\n## CLI Reference\n\n**Agent & Gateway**\n\n| Command | Description |\n|---|---|\n| `miqi onboard` | Interactive setup wizard |\n| `miqi agent` | Start an interactive chat session |\n| `miqi agent -m \"\"` | Send a single prompt and exit |\n| `miqi gateway` | Run the long-running gateway (channels + cron) |\n\n**Status & Diagnostics**\n\n| Command | Description |\n|---|---|\n| `miqi status` | Show runtime and provider status |\n| `miqi channels status` | Show channel connection status |\n\n**Memory Management**\n\n| Command | Description |\n|---|---|\n| `miqi memory status` | Show memory snapshot and stats |\n| `miqi memory flush` | Force-persist pending memory updates immediately |\n| `miqi memory compact [--max-items N]` | Prune long-term snapshot to at most N items |\n| `miqi memory list [--limit N] [--session S]` | Browse long-term snapshot entries |\n| `miqi memory delete ` | Remove a snapshot entry by ID |\n| `miqi memory lessons status` | Show self-improvement lesson stats |\n| `miqi memory lessons list` | List lessons (filter by `--scope`, `--session`, `--limit`) |\n| `miqi memory lessons enable ` | Re-enable a disabled lesson |\n| `miqi memory lessons disable ` | Suppress a lesson from future prompts |\n| `miqi memory lessons delete ` | Permanently remove a lesson |\n| `miqi memory lessons compact [--max-lessons N]` | Prune lessons to at most N entries |\n| `miqi memory lessons reset` | Wipe all lessons |\n\n**Session Management**\n\n| Command | Description |\n|---|---|\n| `miqi session compact --session ` | Compact a single conversation session |\n| `miqi session compact --all` | Compact all stored sessions |\n\n**Cron Scheduler**\n\n| Command | Description |\n|---|---|\n| `miqi cron list` | List all scheduled jobs |\n| `miqi cron add` | Add a new scheduled job |\n| `miqi cron run ` | Trigger a job manually |\n| `miqi cron enable ` | Enable a job |\n| `miqi cron disable ` | Disable a job |\n| `miqi cron remove ` | Remove a job permanently |\n\n**Configuration**\n\n| Command | Description |\n|---|---|\n| `miqi config show` | Print all non-default config values |\n| `miqi config provider ` | Set or update a provider's API key / base URL |\n| `miqi config feishu` | One-shot Feishu channel + feishu-mcp setup |\n| `miqi config pdf2zh` | Configure pdf2zh MCP server (auto-fills LLM credentials) |\n| `miqi config mcp list` | List all configured MCP servers |\n| `miqi config mcp add ` | Add or update an MCP server (stdio or HTTP) |\n| `miqi config mcp remove ` | Remove an MCP server |\n\n**Providers**\n\n| Command | Description |\n|---|---|\n| `miqi provider login openai-codex` | Authenticate with OpenAI Codex (OAuth) |\n\n---\n\n## Core Capabilities\n\n### Memory & Self-Improvement\n\nMiQi uses a RAM-first memory architecture:\n\n- **Session window** β unconsolidated recent context for fast recall, persisted by default as append-only JSONL files under `/sessions/`\n- **Long-term snapshots** β periodic persistence with audit trails under `/memory/`\n- **Lesson extraction** β automatically distills insights from user feedback and tool outcomes\n- **Configurable confidence thresholds** β controls promotion of lessons to long-term memory\n\n### Agent Runtime Controls\n\n- **Iteration budget** β the main loop injects pressure hints as it approaches `maxToolIterations`\n- **Concurrent dispatch** β safe read-only or path-disjoint tool batches run via `asyncio.gather`\n- **Embedded hooks** β the `AgentLoop` constructor exposes optional smart-routing and context-compression controls for programmatic use\n\n### Scheduled Tasks\n\nJobs can be defined as:\n\n- **Interval jobs** β run every N seconds/minutes/hours\n- **Cron expression jobs** β full cron syntax support\n- **One-time jobs** β execute at a specific datetime\n\nAll jobs can be toggled, triggered manually, or removed via the CLI.\n\n### MCP Integration\n\nConnect any MCP-compatible tool server and expose its tools directly to the agent. Define MCP servers under `tools.mcpServers` in your config. For example, connect [feishu-mcp](https://github.com/lichman0405/feishu-mcp) to bring Feishu collaboration capabilities (messages, calendar, tasks, documents) into the agent via a clean MCP interface.\n\nFor long-running MCP tools (e.g. scientific computing), MiQi automatically sends periodic heartbeat progress messages to the user so they know the task is still running. Configure `progressIntervalSeconds` per MCP server (default 15s), increase `toolTimeout` for compute-heavy operations, and use `lazy` mode when a server exposes a large tool surface.\n\n### Task Queue Awareness\n\nWhen multiple users send messages simultaneously (e.g. in a group chat), MiQi queues tasks and notifies each user of their queue position. Users see when their task starts processing and how many tasks are ahead. This is enabled by default via `channels.sendQueueNotifications`.\n\n---\n\n## Development\n\n### Prerequisites\n\n- Python 3.11+\n- Linux or macOS (recommended)\n\n### Run Tests\n\n```bash\nPYTHONPATH=. .venv/bin/pytest -q\n```\n\n### Lint\n\n```bash\n.venv/bin/ruff check .\n```\n\n---\n\n## Migration Guide\n\nIf upgrading from a previous version or migrating from `nanobot`:\n\n| Item | Old | New |\n|---|---|---|\n| Python package | `nanobot.*` | `miqi.*` |\n| CLI command | `assistant` | `miqi` |\n| Runtime directory | `~/.assistant` | `~/.miqi` |\n| Workspace directory | `~/.assistant/workspace` | `~/.miqi/workspace` |\n\nBackward-compatible fallbacks for old config and data paths are retained where possible.\n\n---\n\n## MCP Ecosystem\n\nMiQi ships with seven domain-specific MCP servers as git submodules under `mcps/`.\nThey cover porous-material science, epitaxial surface analysis, PDF translation, and team collaboration.\n\n### Bundled MCP Servers\n\n| Name | Submodule | Python | Description |\n|---|---|---|---|\n| **zeopp** | `mcps/zeopp-backend` | 3.10+ | Zeo++ porous material geometry (volume, pore size, channels) |\n| **raspa2** | `mcps/raspa-mcp` | 3.11+ | RASPA2 molecular simulation β input templates, output parsing |\n| **mofstructure** | `mcps/mofstructure-mcp` | 3.9+ | MOF structural analysis β building blocks, topology, metal nodes |\n| **mofchecker** | `mcps/mofchecker-mcp` | **<3.11** | MOF structure validation β CIF integrity, geometry defects |\n| **miqrophi** | `mcps/miqrophi-mcp` | 3.10+ | Epitaxial lattice matching β CIF surface analysis, substrate screening, strain calculation |\n| **pdf2zh** | `mcps/pdftranslate-mcp` | 3.10β3.12 | PDF paper translation preserving LaTeX layout (needs OpenAI key) |\n| **feishu** | `mcps/feishu-mcp` | 3.11+ | Feishu/Lark β messaging, docs, tasks (needs App ID & Secret) |\n\n### Setup\n\n**1. Clone with submodules** (one-time):\n\n```bash\ngit clone --recurse-submodules https://github.com/lichman0405/miqi.git\n# or, if you already cloned without --recurse-submodules:\ngit submodule update --init --recursive\n```\n\n**2. Install Python venvs** for each MCP:\n\n```bash\nbash scripts/setup_mcps.sh\n```\n\nThe script uses [`uv`](https://docs.astral.sh/uv/) and pins the correct Python version per MCP\n(notably `mofchecker` requires Python 3.10; `pdf2zh` requires β€3.12).\n\n**3. Register MCPs with miqi**:\n\n```bash\nbash scripts/configure_mcps.sh\n```\n\nThis calls `miqi config mcp add` for every server with recommended timeouts and lazy-mode settings.\n\n**4. Add credentials** for the two servers that need them β open `~/.miqi/config.json` and fill in:\n\n```jsonc\n\"tools\": {\n \"mcpServers\": {\n \"pdf2zh\": {\n \"env\": {\n \"OPENAI_BASE_URL\": \"https://api.openai.com/v1\",\n \"OPENAI_API_KEY\": \"sk-...\",\n \"OPENAI_MODEL\": \"gpt-4o\"\n }\n },\n \"feishu\": {\n \"env\": {\n \"FEISHU_APP_ID\": \"cli_...\",\n \"FEISHU_APP_SECRET\": \"...\"\n }\n }\n }\n}\n```\n\n> **Security note**: MCP subprocesses launched via the stdio transport inherit only a minimal environment\n> (`HOME`, `PATH`, `SHELL`, `USER`, `TERM`, `LOGNAME`) β your LLM provider API keys are never exposed\n> to MCP servers unless you explicitly add them to `cfg.env` as shown above.\n\n---\n\n## Documentation Index\n\n### Root Documents\n\n- [README.md](README.md)\n- [CHANGELOG.md](CHANGELOG.md)\n- [CONTRIBUTING.md](CONTRIBUTING.md)\n\n### Project Docs (`docs/`)\n\n- [docs/index.md](docs/index.md)\n- [docs/getting-started.md](docs/getting-started.md)\n- [docs/configuration.md](docs/configuration.md)\n- [docs/cli-reference.md](docs/cli-reference.md)\n- [docs/mcp-integration.md](docs/mcp-integration.md)\n- [docs/architecture.md](docs/architecture.md)\n- [docs/memory-system.md](docs/memory-system.md)\n- [docs/self-improvement.md](docs/self-improvement.md)\n- [docs/security.md](docs/security.md)\n- [docs/developer-guide.md](docs/developer-guide.md)\n- [docs/changelog.md](docs/changelog.md)\n\n### Scripts (`scripts/`)\n\n- [scripts/setup_mcps.sh](scripts/setup_mcps.sh) β Create isolated Python venvs for all bundled MCP servers\n- [scripts/configure_mcps.sh](scripts/configure_mcps.sh) β Register all bundled MCPs into `~/.miqi/config.json`\n\n### Skills Docs (`miqi/skills/`)\n\n- [miqi/skills/README.md](miqi/skills/README.md)\n- [miqi/skills/cron/SKILL.md](miqi/skills/cron/SKILL.md)\n- [miqi/skills/feishu-report/SKILL.md](miqi/skills/feishu-report/SKILL.md)\n- [miqi/skills/github/SKILL.md](miqi/skills/github/SKILL.md)\n- [miqi/skills/memory/SKILL.md](miqi/skills/memory/SKILL.md)\n- [miqi/skills/paper-research/SKILL.md](miqi/skills/paper-research/SKILL.md)\n- [miqi/skills/skill-creator/SKILL.md](miqi/skills/skill-creator/SKILL.md)\n- [miqi/skills/summarize/SKILL.md](miqi/skills/summarize/SKILL.md)\n- [miqi/skills/tmux/SKILL.md](miqi/skills/tmux/SKILL.md)\n- [miqi/skills/weather/SKILL.md](miqi/skills/weather/SKILL.md)\n- [miqi/skills/workspace-cleanup/SKILL.md](miqi/skills/workspace-cleanup/SKILL.md)\n\n### Template Docs (`miqi/templates/`)\n\n- [miqi/templates/AGENTS.md](miqi/templates/AGENTS.md)\n- [miqi/templates/HEARTBEAT.md](miqi/templates/HEARTBEAT.md)\n- [miqi/templates/SOUL.md](miqi/templates/SOUL.md)\n- [miqi/templates/TOOLS.md](miqi/templates/TOOLS.md)\n- [miqi/templates/USER.md](miqi/templates/USER.md)\n- [miqi/templates/memory/MEMORY.md](miqi/templates/memory/MEMORY.md)\n\n---\n\n## License\n\n[MIT](LICENSE)\n"}, "eb7a764edeb7dce54b4130d69b5cff269c89418b": {"t": 1785771697.4943438, "n": 19275, "h": "99b26649f36c9663", "c": "# MiQi\n\n\n πββ¬πͺΆ A lightweight, extensible personal AI agent framework for production automation and conversational workflows.\n
\n\n\n \n \n \n \n \n \n
\n\n---\n\n## Overview\n\nMiQi is a compact AI agent runtime designed for developers who want a self-hosted, programmable assistant. It connects to any OpenAI-compatible LLM provider and exposes a rich toolset β file operations, shell execution, web search, scheduled tasks, sub-agents, and external MCP servers β all configurable via a single JSON file.\n\nMiQi is a domain-focused evolution of the upstream [`nanobot`](https://github.com/HKUDS/nanobot) project. Full credit to the upstream team for the excellent engineering baseline in runtime design and tool abstraction.\n\n> **Reference baseline:** `nanobot` @ [`30361c9`](https://github.com/HKUDS/nanobot/commit/30361c9307f9014f49530d80abd5717bc97f554a) (2026-02-23)\n\n---\n\n## Features\n\n| Category | Capabilities |\n|---|---|\n| **LLM Providers** | OpenRouter, OpenAI, Anthropic, DeepSeek, Gemini, Groq, Moonshot, MiniMax, ZhipuAI, DashScope (Qwen), SiliconFlow, VolcEngine, AiHubMix, vLLM, Ollama, OpenAI Codex (OAuth), and any OpenAI-compatible endpoint |\n| **Built-in Tools** | File system, shell, web fetch/search, paper research (search/details/download), cron scheduler, sub-agent spawning |\n| **Channels** | Channel adapters exist for Feishu/Telegram/Discord/Slack/Email/QQ/DingTalk/MoChat (runtime wiring via config) |\n| **MCP Integration** | Connect any MCP-compatible tool server (e.g. [feishu-mcp](https://github.com/lichman0405/feishu-mcp)) |\n| **Memory** | RAM-first with snapshots, lesson extraction, and compact session history |\n| **Extensibility** | MCP server integration, skill files, custom provider plugins |\n| **CLI** | Interactive onboarding, agent chat, gateway mode, cron and memory management |\n\n---\n\n## Quick Start\n\n### Installation\n\n```bash\n# Clone the repository\ngit clone https://github.com/lichman0405/miqi.git\ncd miqi\n\n# Create and activate a virtual environment\npython3 -m venv .venv\nsource .venv/bin/activate\n\n# Install MiQi\npip install --upgrade pip\npip install -e .\n\n# Verify\nmiqi --version\n```\n\n### First Run\n\n```bash\n# Interactive setup wizard β configures your provider, model, and identity\nmiqi onboard\n\n# Send a one-shot message\nmiqi agent -m \"hello\"\n\n# Start an interactive chat session\nmiqi agent\n\n# Launch the long-running gateway (channels + scheduled jobs)\nmiqi gateway\n```\n\n`miqi onboard` now also supports:\n\n- Paper research tool configuration (`tools.papers` provider, API key, limits)\n\n---\n\n## Installation Options\n\n### With Dev Dependencies\n\n```bash\npip install -e '.[dev]'\n```\n\n### Docker (Recommended for Production)\n\n```bash\n# Start the gateway\ndocker compose up --build miqi-gateway\n\n# Run a one-off CLI command in the container\ndocker compose --profile cli run --rm miqi-cli status\n```\n\n**Runtime data directory mapping:**\n\n| Location | Path |\n|---|---|\n| Host | `~/.miqi` |\n| Container | `/home/miqi/.miqi` |\n\n> **Security:** The container runs as unprivileged user `miqi` (UID 1000) β not root. The gateway port (`18790`) is bound to `127.0.0.1` by default and is **not** exposed to the network. Use a reverse proxy (e.g. Nginx) to expose it externally.\n\n### Bare-Metal (Non-Docker) Deployment\n\nFor running the gateway directly on a Linux/macOS host as a long-running service:\n\n**1. Prepare configuration** (if not done already):\n\n```bash\n# Interactive setup β creates ~/.miqi/config.json\nmiqi onboard\n\n# Verify the config\nmiqi status\n```\n\n**2. (Optional) Set up MCP servers:**\n\n```bash\nbash scripts/setup_mcps.sh # install isolated venvs\nbash scripts/configure_mcps.sh # register MCPs into config\n```\n\n**3. Run with systemd** (Linux, recommended):\n\nCreate `/etc/systemd/system/miqi.service`:\n\n```ini\n[Unit]\nDescription=MiQi AI Agent Gateway\nAfter=network.target\n\n[Service]\nType=simple\nUser=miqi\nWorkingDirectory=/home/miqi\nExecStart=/home/miqi/.local/bin/miqi gateway\nRestart=on-failure\nRestartSec=10\nEnvironment=HOME=/home/miqi\n\n[Install]\nWantedBy=multi-user.target\n```\n\n```bash\nsudo systemctl daemon-reload\nsudo systemctl enable --now miqi\nsudo journalctl -u miqi -f # tail logs\n```\n\nOn macOS, use `launchd` or a process manager like `supervisord` instead.\n\n**4. Reverse proxy** (optional, for external access):\n\nThe gateway listens on `127.0.0.1:18790`. To expose it, place it behind Nginx:\n\n```nginx\nserver {\n listen 443 ssl;\n server_name miqi.example.com;\n\n location / {\n proxy_pass http://127.0.0.1:18790;\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n }\n}\n```\n\n### Upgrading\n\n```bash\ncd miqi\ngit pull --recurse-submodules\npip install -e . # reinstall core\nbash scripts/setup_mcps.sh # update MCP venvs\nbash scripts/configure_mcps.sh # re-register MCPs (idempotent)\n# then restart the gateway (systemctl restart miqi / docker compose up --build)\n```\n\n> **Note:** The Docker image does **not** include MCP submodules β MCP servers run as separate stdio subprocesses on the host. When using Docker, mount or install MCP venvs on the host and configure `tools.mcpServers` commands to point at host-side interpreters, or run MCP servers as separate containers and use HTTP transport (`url` instead of `command`).\n\n---\n\n## Configuration\n\nMiQi reads from `~/.miqi/config.json`. The interactive wizard (`miqi onboard`) can generate this file for you.\n\n**Default paths:**\n\n| Item | Path |\n|---|---|\n| Config file | `~/.miqi/config.json` |\n| Workspace | `~/.miqi/workspace` |\n\n### Configuration Skeleton\n\n```json\n{\n \"providers\": {\n \"openrouter\": {\n \"apiKey\": \"sk-or-v1-xxx\"\n }\n },\n \"agents\": {\n \"defaults\": {\n \"model\": \"anthropic/claude-opus-4-5\",\n \"name\": \"miqi\",\n \"temperature\": 0.7\n }\n },\n \"channels\": {\n },\n \"tools\": {\n \"web\": {\n \"enabled\": true\n }\n },\n \"heartbeat\": {\n \"enabled\": true,\n \"intervalSeconds\": 1800\n }\n}\n```\n\n### Key Sections\n\n- **`providers`** β API keys, custom `apiBase` URLs, and optional `extraHeaders` (e.g. `APP-Code` for AiHubMix) for each LLM provider.\n- **`agents.defaults`** β Default model, temperature, `maxTokens`, `maxToolIterations`, `memoryWindow`, and agent identity (`name`, `workspace`).\n- **`agents.memory`** β Memory flush cadence (`flushEveryUpdates`, `flushIntervalSeconds`) and short-term window sizes.\n- **`agents.sessions`** β Session compaction thresholds (`compactThresholdMessages`, `compactThresholdBytes`, `compactKeepMessages`).\n- **`agents.selfImprovement`** β Lesson extraction settings: `enabled`, `maxLessonsInPrompt`, `minLessonConfidence`, `maxLessons`, `promotionEnabled`, etc.\n- **`channels`** β Channel configuration for each IM adapter; also controls `sendProgress` (stream text to channel), `sendToolHints` (stream tool-call hints), and `sendQueueNotifications` (notify users about task queue position).\n - **`channels.feishu.requireMentionInGroups`** β When `true` (default), the bot only responds to group messages where it is @mentioned. Private chats are unaffected.\n- **`gateway`** β HTTP gateway listen address (`host`, `port`; default `0.0.0.0:18790` for bare-metal runs). When using Docker Compose the port is bound to `127.0.0.1:18790` by default.\n- **`tools`** β Web/search/fetch behavior, paper research provider settings (`tools.papers`), shell execution policy (`tools.exec.timeout`), `restrictToWorkspace` flag, and MCP server definitions (`tools.mcpServers`).\n - **`tools.mcpServers..progressIntervalSeconds`** β Heartbeat interval (seconds) for long-running MCP tool calls. Set to `0` to disable. Default `15`.\n - **`tools.mcpServers..toolTimeout`** β Timeout in seconds before a tool call is cancelled. For scientific computing MCP servers (e.g. raspa, mofstructure), set to `300`β`600`. Default `30`.\n - **`tools.mcpServers..allowedTools`** β Optional allowlist of tool names. When non-empty, only the listed tools from this MCP server are registered. All others are silently dropped.\n - **`tools.mcpServers..deniedTools`** β Optional denylist of tool names. Any tool whose name appears here is never registered, regardless of `allowedTools`.\n- **`heartbeat`** β Periodic background prompts (`enabled`, `intervalSeconds`) for proactive agent behaviors.\n\n> **Security:** Config files are automatically saved with `0600` permissions (owner-read-only) to protect API keys. Set strict `allowFrom` lists before exposing to any channel. See [`docs/SECURITY.md`](docs/SECURITY.md) for full guidance.\n\n### Environment Variable Overrides\n\nEvery config field can be overridden at runtime via environment variables using the prefix `MIQI_` and `__` as the nesting delimiter:\n\n```bash\n# Override the default model\nMIQI_AGENTS__DEFAULTS__MODEL=deepseek/deepseek-chat miqi agent\n\n# Inject an API key without editing config.json\nMIQI_PROVIDERS__OPENROUTER__API_KEY=sk-or-v1-xxx miqi gateway\n```\n\nThis is particularly useful in containerised deployments where secrets are injected as environment variables rather than mounted files.\n\n---\n\n## CLI Reference\n\n**Agent & Gateway**\n\n| Command | Description |\n|---|---|\n| `miqi onboard` | Interactive setup wizard |\n| `miqi agent` | Start an interactive chat session |\n| `miqi agent -m \"\"` | Send a single prompt and exit |\n| `miqi gateway` | Run the long-running gateway (channels + cron) |\n\n**Status & Diagnostics**\n\n| Command | Description |\n|---|---|\n| `miqi status` | Show runtime and provider status |\n| `miqi channels status` | Show channel connection status |\n\n**Memory Management**\n\n| Command | Description |\n|---|---|\n| `miqi memory status` | Show memory snapshot and stats |\n| `miqi memory flush` | Force-persist pending memory updates immediately |\n| `miqi memory compact [--max-items N]` | Prune long-term snapshot to at most N items |\n| `miqi memory list [--limit N] [--session S]` | Browse long-term snapshot entries |\n| `miqi memory delete ` | Remove a snapshot entry by ID |\n| `miqi memory lessons status` | Show self-improvement lesson stats |\n| `miqi memory lessons list` | List lessons (filter by `--scope`, `--session`, `--limit`) |\n| `miqi memory lessons enable ` | Re-enable a disabled lesson |\n| `miqi memory lessons disable ` | Suppress a lesson from future prompts |\n| `miqi memory lessons delete ` | Permanently remove a lesson |\n| `miqi memory lessons compact [--max-lessons N]` | Prune lessons to at most N entries |\n| `miqi memory lessons reset` | Wipe all lessons |\n\n**Session Management**\n\n| Command | Description |\n|---|---|\n| `miqi session compact --session ` | Compact a single conversation session |\n| `miqi session compact --all` | Compact all stored sessions |\n\n**Cron Scheduler**\n\n| Command | Description |\n|---|---|\n| `miqi cron list` | List all scheduled jobs |\n| `miqi cron add` | Add a new scheduled job |\n| `miqi cron run ` | Trigger a job manually |\n| `miqi cron enable ` | Enable a job |\n| `miqi cron disable ` | Disable a job |\n| `miqi cron remove ` | Remove a job permanently |\n\n**Configuration**\n\n| Command | Description |\n|---|---|\n| `miqi config show` | Print all non-default config values |\n| `miqi config provider ` | Set or update a provider's API key / base URL |\n| `miqi config feishu` | One-shot Feishu channel + feishu-mcp setup |\n| `miqi config pdf2zh` | Configure pdf2zh MCP server (auto-fills LLM credentials) |\n| `miqi config mcp list` | List all configured MCP servers |\n| `miqi config mcp add ` | Add or update an MCP server (stdio or HTTP) |\n| `miqi config mcp remove ` | Remove an MCP server |\n\n**Providers**\n\n| Command | Description |\n|---|---|\n| `miqi provider login openai-codex` | Authenticate with OpenAI Codex (OAuth) |\n\n---\n\n## Core Capabilities\n\n### Memory & Self-Improvement\n\nMiQi uses a RAM-first memory architecture:\n\n- **Session window** β unconsolidated recent context for fast recall\n- **Long-term snapshots** β periodic persistence with audit trails\n- **Lesson extraction** β automatically distills insights from user feedback and tool outcomes\n- **Configurable confidence thresholds** β controls promotion of lessons to long-term memory\n\n### Scheduled Tasks\n\nJobs can be defined as:\n\n- **Interval jobs** β run every N seconds/minutes/hours\n- **Cron expression jobs** β full cron syntax support\n- **One-time jobs** β execute at a specific datetime\n\nAll jobs can be toggled, triggered manually, or removed via the CLI.\n\n### MCP Integration\n\nConnect any MCP-compatible tool server and expose its tools directly to the agent. Define MCP servers under `tools.mcpServers` in your config. For example, connect [feishu-mcp](https://github.com/lichman0405/feishu-mcp) to bring Feishu collaboration capabilities (messages, calendar, tasks, documents) into the agent via a clean MCP interface.\n\nFor long-running MCP tools (e.g. scientific computing), MiQi automatically sends periodic heartbeat progress messages to the user so they know the task is still running. Configure `progressIntervalSeconds` per MCP server (default 15s) and increase `toolTimeout` for compute-heavy operations.\n\n### Task Queue Awareness\n\nWhen multiple users send messages simultaneously (e.g. in a group chat), MiQi queues tasks and notifies each user of their queue position. Users see when their task starts processing and how many tasks are ahead. This is enabled by default via `channels.sendQueueNotifications`.\n\n---\n\n## Development\n\n### Prerequisites\n\n- Python 3.11+\n- Linux or macOS (recommended)\n\n### Run Tests\n\n```bash\nPYTHONPATH=. .venv/bin/pytest -q\n```\n\n### Lint\n\n```bash\n.venv/bin/ruff check .\n```\n\n---\n\n## Migration Guide\n\nIf upgrading from a previous version or migrating from `nanobot`:\n\n| Item | Old | New |\n|---|---|---|\n| Python package | `nanobot.*` | `miqi.*` |\n| CLI command | `assistant` | `miqi` |\n| Runtime directory | `~/.assistant` | `~/.miqi` |\n| Workspace directory | `~/.assistant/workspace` | `~/.miqi/workspace` |\n\nBackward-compatible fallbacks for old config and data paths are retained where possible.\n\n---\n\n## MCP Ecosystem\n\nMiQi ships with seven domain-specific MCP servers as git submodules under `mcps/`.\nThey cover porous-material science, epitaxial surface analysis, PDF translation, and team collaboration.\n\n### Bundled MCP Servers\n\n| Name | Submodule | Python | Description |\n|---|---|---|---|\n| **zeopp** | `mcps/zeopp-backend` | 3.10+ | Zeo++ porous material geometry (volume, pore size, channels) |\n| **raspa2** | `mcps/raspa-mcp` | 3.11+ | RASPA2 molecular simulation β input templates, output parsing |\n| **mofstructure** | `mcps/mofstructure-mcp` | 3.9+ | MOF structural analysis β building blocks, topology, metal nodes |\n| **mofchecker** | `mcps/mofchecker-mcp` | **<3.11** | MOF structure validation β CIF integrity, geometry defects |\n| **miqrophi** | `mcps/miqrophi-mcp` | 3.10+ | Epitaxial lattice matching β CIF surface analysis, substrate screening, strain calculation |\n| **pdf2zh** | `mcps/pdftranslate-mcp` | 3.10β3.12 | PDF paper translation preserving LaTeX layout (needs OpenAI key) |\n| **feishu** | `mcps/feishu-mcp` | 3.11+ | Feishu/Lark β messaging, docs, tasks (needs App ID & Secret) |\n\n### Setup\n\n**1. Clone with submodules** (one-time):\n\n```bash\ngit clone --recurse-submodules https://github.com/lichman0405/miqi.git\n# or, if you already cloned without --recurse-submodules:\ngit submodule update --init --recursive\n```\n\n**2. Install Python venvs** for each MCP:\n\n```bash\nbash scripts/setup_mcps.sh\n```\n\nThe script uses [`uv`](https://docs.astral.sh/uv/) and pins the correct Python version per MCP\n(notably `mofchecker` requires Python 3.10; `pdf2zh` requires β€3.12).\n\n**3. Register MCPs with miqi**:\n\n```bash\nbash scripts/configure_mcps.sh\n```\n\nThis calls `miqi config mcp add` for every server with recommended timeouts and lazy-mode settings.\n\n**4. Add credentials** for the two servers that need them β open `~/.miqi/config.json` and fill in:\n\n```jsonc\n\"tools\": {\n \"mcpServers\": {\n \"pdf2zh\": {\n \"env\": {\n \"OPENAI_BASE_URL\": \"https://api.openai.com/v1\",\n \"OPENAI_API_KEY\": \"sk-...\",\n \"OPENAI_MODEL\": \"gpt-4o\"\n }\n },\n \"feishu\": {\n \"env\": {\n \"FEISHU_APP_ID\": \"cli_...\",\n \"FEISHU_APP_SECRET\": \"...\"\n }\n }\n }\n}\n```\n\n> **Security note**: MCP subprocesses launched via the stdio transport inherit only a minimal environment\n> (`HOME`, `PATH`, `SHELL`, `USER`, `TERM`, `LOGNAME`) β your LLM provider API keys are never exposed\n> to MCP servers unless you explicitly add them to `cfg.env` as shown above.\n\n---\n\n## Documentation Index\n\n### Root Documents\n\n- [README.md](README.md)\n- [CHANGELOG.md](CHANGELOG.md)\n- [CONTRIBUTING.md](CONTRIBUTING.md)\n\n### Project Docs (`docs/`)\n\n- [docs/API.md](docs/API.md)\n- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)\n- [docs/DEVELOPER_GUIDE.md](docs/DEVELOPER_GUIDE.md)\n- [docs/RAM_FIRST_MEMORY_CHECKPOINT.md](docs/RAM_FIRST_MEMORY_CHECKPOINT.md)\n- [docs/SECURITY.md](docs/SECURITY.md)\n- [docs/SECURITY_IMPROVEMENTS.md](docs/SECURITY_IMPROVEMENTS.md)\n- [docs/SELF_DEVELOPMENT.md](docs/SELF_DEVELOPMENT.md)\n\n### Scripts (`scripts/`)\n\n- [scripts/setup_mcps.sh](scripts/setup_mcps.sh) β Create isolated Python venvs for all bundled MCP servers\n- [scripts/configure_mcps.sh](scripts/configure_mcps.sh) β Register all bundled MCPs into `~/.miqi/config.json`\n\n### Skills Docs (`miqi/skills/`)\n\n- [miqi/skills/README.md](miqi/skills/README.md)\n- [miqi/skills/cron/SKILL.md](miqi/skills/cron/SKILL.md)\n- [miqi/skills/feishu-report/SKILL.md](miqi/skills/feishu-report/SKILL.md)\n- [miqi/skills/github/SKILL.md](miqi/skills/github/SKILL.md)\n- [miqi/skills/memory/SKILL.md](miqi/skills/memory/SKILL.md)\n- [miqi/skills/paper-research/SKILL.md](miqi/skills/paper-research/SKILL.md)\n- [miqi/skills/skill-creator/SKILL.md](miqi/skills/skill-creator/SKILL.md)\n- [miqi/skills/summarize/SKILL.md](miqi/skills/summarize/SKILL.md)\n- [miqi/skills/tmux/SKILL.md](miqi/skills/tmux/SKILL.md)\n- [miqi/skills/weather/SKILL.md](miqi/skills/weather/SKILL.md)\n- [miqi/skills/workspace-cleanup/SKILL.md](miqi/skills/workspace-cleanup/SKILL.md)\n\n### Template Docs (`miqi/templates/`)\n\n- [miqi/templates/AGENTS.md](miqi/templates/AGENTS.md)\n- [miqi/templates/HEARTBEAT.md](miqi/templates/HEARTBEAT.md)\n- [miqi/templates/SOUL.md](miqi/templates/SOUL.md)\n- [miqi/templates/TOOLS.md](miqi/templates/TOOLS.md)\n- [miqi/templates/USER.md](miqi/templates/USER.md)\n- [miqi/templates/memory/MEMORY.md](miqi/templates/memory/MEMORY.md)\n\n---\n\n## License\n\n[MIT](LICENSE)\n"}, "a88c651f52a298cfd7dfe99231810fbc9c797666": {"t": 1785771699.8383176, "n": 20164, "h": "c60f91f7fb3dd974", "c": "# FeatherFlow\n\n\n πββ¬πͺΆ A lightweight, extensible personal AI agent framework for production automation and conversational workflows.\n
\n\n\n \n \n \n \n \n \n
\n\n---\n\n## Overview\n\nFeatherFlow is a compact AI agent runtime designed for developers who want a self-hosted, programmable assistant. It connects to any OpenAI-compatible LLM provider and exposes a rich toolset β file operations, shell execution, web search, scheduled tasks, sub-agents, and external MCP servers β all configurable via a single JSON file.\n\nFeatherFlow is a domain-focused evolution of the upstream [`nanobot`](https://github.com/HKUDS/nanobot) project. Full credit to the upstream team for the excellent engineering baseline in runtime design and tool abstraction.\n\n> **Reference baseline:** `nanobot` @ [`30361c9`](https://github.com/HKUDS/nanobot/commit/30361c9307f9014f49530d80abd5717bc97f554a) (2026-02-23)\n\n---\n\n## Features\n\n| Category | Capabilities |\n|---|---|\n| **LLM Providers** | OpenRouter, OpenAI, Anthropic, DeepSeek, Gemini, Groq, Moonshot, MiniMax, ZhipuAI, DashScope (Qwen), SiliconFlow, VolcEngine, AiHubMix, vLLM, Ollama, OpenAI Codex (OAuth), and any OpenAI-compatible endpoint |\n| **Built-in Tools** | File system, shell, web fetch/search, paper research (search/details/download), cron scheduler, sub-agent spawning |\n| **Channels** | Channel adapters exist for Feishu/Telegram/Discord/Slack/Email/QQ/DingTalk/MoChat (runtime wiring via config) |\n| **MCP Integration** | Connect any MCP-compatible tool server (e.g. [feishu-mcp](https://github.com/lichman0405/feishu-mcp)) |\n| **Memory** | RAM-first with snapshots, lesson extraction, and compact session history |\n| **Extensibility** | MCP server integration, skill files, custom provider plugins |\n| **CLI** | Interactive onboarding, agent chat, gateway mode, cron and memory management |\n\n---\n\n## Quick Start\n\n### Installation\n\n```bash\n# Clone the repository\ngit clone https://github.com/lichman0405/featherflow.git\ncd featherflow\n\n# Create and activate a virtual environment\npython3 -m venv .venv\nsource .venv/bin/activate\n\n# Install FeatherFlow\npip install --upgrade pip\npip install -e .\n\n# Verify\nfeatherflow --version\n```\n\n### First Run\n\n```bash\n# Interactive setup wizard β configures your provider, model, and identity\nfeatherflow onboard\n\n# Send a one-shot message\nfeatherflow agent -m \"hello\"\n\n# Start an interactive chat session\nfeatherflow agent\n\n# Launch the long-running gateway (channels + scheduled jobs)\nfeatherflow gateway\n```\n\n`featherflow onboard` now also supports:\n\n- Paper research tool configuration (`tools.papers` provider, API key, limits)\n\n---\n\n## Installation Options\n\n### With Dev Dependencies\n\n```bash\npip install -e '.[dev]'\n```\n\n### Docker (Recommended for Production)\n\n```bash\n# Start the gateway\ndocker compose up --build featherflow-gateway\n\n# Run a one-off CLI command in the container\ndocker compose --profile cli run --rm featherflow-cli status\n```\n\n**Runtime data directory mapping:**\n\n| Location | Path |\n|---|---|\n| Host | `~/.featherflow` |\n| Container | `/home/featherflow/.featherflow` |\n\n> **Security:** The container runs as unprivileged user `featherflow` (UID 1000) β not root. The gateway port (`18790`) is bound to `127.0.0.1` by default and is **not** exposed to the network. Use a reverse proxy (e.g. Nginx) to expose it externally.\n\n### Bare-Metal (Non-Docker) Deployment\n\nFor running the gateway directly on a Linux/macOS host as a long-running service:\n\n**1. Prepare configuration** (if not done already):\n\n```bash\n# Interactive setup β creates ~/.featherflow/config.json\nfeatherflow onboard\n\n# Verify the config\nfeatherflow status\n```\n\n**2. (Optional) Set up MCP servers:**\n\n```bash\nbash scripts/setup_mcps.sh # install isolated venvs\nbash scripts/configure_mcps.sh # register MCPs into config\n```\n\n**3. Run with systemd** (Linux, recommended):\n\nCreate `/etc/systemd/system/featherflow.service`:\n\n```ini\n[Unit]\nDescription=FeatherFlow AI Agent Gateway\nAfter=network.target\n\n[Service]\nType=simple\nUser=featherflow\nWorkingDirectory=/home/featherflow\nExecStart=/home/featherflow/.local/bin/featherflow gateway\nRestart=on-failure\nRestartSec=10\nEnvironment=HOME=/home/featherflow\n\n[Install]\nWantedBy=multi-user.target\n```\n\n```bash\nsudo systemctl daemon-reload\nsudo systemctl enable --now featherflow\nsudo journalctl -u featherflow -f # tail logs\n```\n\nOn macOS, use `launchd` or a process manager like `supervisord` instead.\n\n**4. Reverse proxy** (optional, for external access):\n\nThe gateway listens on `127.0.0.1:18790`. To expose it, place it behind Nginx:\n\n```nginx\nserver {\n listen 443 ssl;\n server_name featherflow.example.com;\n\n location / {\n proxy_pass http://127.0.0.1:18790;\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n }\n}\n```\n\n### Upgrading\n\n```bash\ncd featherflow\ngit pull --recurse-submodules\npip install -e . # reinstall core\nbash scripts/setup_mcps.sh # update MCP venvs\nbash scripts/configure_mcps.sh # re-register MCPs (idempotent)\n# then restart the gateway (systemctl restart featherflow / docker compose up --build)\n```\n\n> **Note:** The Docker image does **not** include MCP submodules β MCP servers run as separate stdio subprocesses on the host. When using Docker, mount or install MCP venvs on the host and configure `tools.mcpServers` commands to point at host-side interpreters, or run MCP servers as separate containers and use HTTP transport (`url` instead of `command`).\n\n---\n\n## Configuration\n\nFeatherFlow reads from `~/.featherflow/config.json`. The interactive wizard (`featherflow onboard`) can generate this file for you.\n\n**Default paths:**\n\n| Item | Path |\n|---|---|\n| Config file | `~/.featherflow/config.json` |\n| Workspace | `~/.featherflow/workspace` |\n\n### Configuration Skeleton\n\n```json\n{\n \"providers\": {\n \"openrouter\": {\n \"apiKey\": \"sk-or-v1-xxx\"\n }\n },\n \"agents\": {\n \"defaults\": {\n \"model\": \"anthropic/claude-opus-4-5\",\n \"name\": \"featherflow\",\n \"temperature\": 0.7\n }\n },\n \"channels\": {\n },\n \"tools\": {\n \"web\": {\n \"enabled\": true\n }\n },\n \"heartbeat\": {\n \"enabled\": true,\n \"intervalSeconds\": 1800\n }\n}\n```\n\n### Key Sections\n\n- **`providers`** β API keys, custom `apiBase` URLs, and optional `extraHeaders` (e.g. `APP-Code` for AiHubMix) for each LLM provider.\n- **`agents.defaults`** β Default model, temperature, `maxTokens`, `maxToolIterations`, `memoryWindow`, and agent identity (`name`, `workspace`).\n- **`agents.memory`** β Memory flush cadence (`flushEveryUpdates`, `flushIntervalSeconds`) and short-term window sizes.\n- **`agents.sessions`** β Session compaction thresholds (`compactThresholdMessages`, `compactThresholdBytes`, `compactKeepMessages`).\n- **`agents.selfImprovement`** β Lesson extraction settings: `enabled`, `maxLessonsInPrompt`, `minLessonConfidence`, `maxLessons`, `promotionEnabled`, etc.\n- **`channels`** β Channel configuration for each IM adapter; also controls `sendProgress` (stream text to channel), `sendToolHints` (stream tool-call hints), and `sendQueueNotifications` (notify users about task queue position).\n - **`channels.feishu.requireMentionInGroups`** β When `true` (default), the bot only responds to group messages where it is @mentioned. Private chats are unaffected.\n- **`gateway`** β HTTP gateway listen address (`host`, `port`; default `0.0.0.0:18790` for bare-metal runs). When using Docker Compose the port is bound to `127.0.0.1:18790` by default.\n- **`tools`** β Web/search/fetch behavior, paper research provider settings (`tools.papers`), shell execution policy (`tools.exec.timeout`), `restrictToWorkspace` flag, and MCP server definitions (`tools.mcpServers`).\n - **`tools.mcpServers..progressIntervalSeconds`** β Heartbeat interval (seconds) for long-running MCP tool calls. Set to `0` to disable. Default `15`.\n - **`tools.mcpServers..toolTimeout`** β Timeout in seconds before a tool call is cancelled. For scientific computing MCP servers (e.g. raspa, mofstructure), set to `300`β`600`. Default `30`.\n - **`tools.mcpServers..allowedTools`** β Optional allowlist of tool names. When non-empty, only the listed tools from this MCP server are registered. All others are silently dropped.\n - **`tools.mcpServers..deniedTools`** β Optional denylist of tool names. Any tool whose name appears here is never registered, regardless of `allowedTools`.\n- **`heartbeat`** β Periodic background prompts (`enabled`, `intervalSeconds`) for proactive agent behaviors.\n\n> **Security:** Config files are automatically saved with `0600` permissions (owner-read-only) to protect API keys. Set strict `allowFrom` lists before exposing to any channel. See [`docs/SECURITY.md`](docs/SECURITY.md) for full guidance.\n\n### Environment Variable Overrides\n\nEvery config field can be overridden at runtime via environment variables using the prefix `FEATHERFLOW_` and `__` as the nesting delimiter:\n\n```bash\n# Override the default model\nFEATHERFLOW_AGENTS__DEFAULTS__MODEL=deepseek/deepseek-chat featherflow agent\n\n# Inject an API key without editing config.json\nFEATHERFLOW_PROVIDERS__OPENROUTER__API_KEY=sk-or-v1-xxx featherflow gateway\n```\n\nThis is particularly useful in containerised deployments where secrets are injected as environment variables rather than mounted files.\n\n---\n\n## CLI Reference\n\n**Agent & Gateway**\n\n| Command | Description |\n|---|---|\n| `featherflow onboard` | Interactive setup wizard |\n| `featherflow agent` | Start an interactive chat session |\n| `featherflow agent -m \"\"` | Send a single prompt and exit |\n| `featherflow gateway` | Run the long-running gateway (channels + cron) |\n\n**Status & Diagnostics**\n\n| Command | Description |\n|---|---|\n| `featherflow status` | Show runtime and provider status |\n| `featherflow channels status` | Show channel connection status |\n\n**Memory Management**\n\n| Command | Description |\n|---|---|\n| `featherflow memory status` | Show memory snapshot and stats |\n| `featherflow memory flush` | Force-persist pending memory updates immediately |\n| `featherflow memory compact [--max-items N]` | Prune long-term snapshot to at most N items |\n| `featherflow memory list [--limit N] [--session S]` | Browse long-term snapshot entries |\n| `featherflow memory delete ` | Remove a snapshot entry by ID |\n| `featherflow memory lessons status` | Show self-improvement lesson stats |\n| `featherflow memory lessons list` | List lessons (filter by `--scope`, `--session`, `--limit`) |\n| `featherflow memory lessons enable ` | Re-enable a disabled lesson |\n| `featherflow memory lessons disable ` | Suppress a lesson from future prompts |\n| `featherflow memory lessons delete ` | Permanently remove a lesson |\n| `featherflow memory lessons compact [--max-lessons N]` | Prune lessons to at most N entries |\n| `featherflow memory lessons reset` | Wipe all lessons |\n\n**Session Management**\n\n| Command | Description |\n|---|---|\n| `featherflow session compact --session ` | Compact a single conversation session |\n| `featherflow session compact --all` | Compact all stored sessions |\n\n**Cron Scheduler**\n\n| Command | Description |\n|---|---|\n| `featherflow cron list` | List all scheduled jobs |\n| `featherflow cron add` | Add a new scheduled job |\n| `featherflow cron run ` | Trigger a job manually |\n| `featherflow cron enable ` | Enable a job |\n| `featherflow cron disable ` | Disable a job |\n| `featherflow cron remove ` | Remove a job permanently |\n\n**Configuration**\n\n| Command | Description |\n|---|---|\n| `featherflow config show` | Print all non-default config values |\n| `featherflow config provider ` | Set or update a provider's API key / base URL |\n| `featherflow config feishu` | One-shot Feishu channel + feishu-mcp setup |\n| `featherflow config pdf2zh` | Configure pdf2zh MCP server (auto-fills LLM credentials) |\n| `featherflow config mcp list` | List all configured MCP servers |\n| `featherflow config mcp add ` | Add or update an MCP server (stdio or HTTP) |\n| `featherflow config mcp remove ` | Remove an MCP server |\n\n**Providers**\n\n| Command | Description |\n|---|---|\n| `featherflow provider login openai-codex` | Authenticate with OpenAI Codex (OAuth) |\n\n---\n\n## Core Capabilities\n\n### Memory & Self-Improvement\n\nFeatherFlow uses a RAM-first memory architecture:\n\n- **Session window** β unconsolidated recent context for fast recall\n- **Long-term snapshots** β periodic persistence with audit trails\n- **Lesson extraction** β automatically distills insights from user feedback and tool outcomes\n- **Configurable confidence thresholds** β controls promotion of lessons to long-term memory\n\n### Scheduled Tasks\n\nJobs can be defined as:\n\n- **Interval jobs** β run every N seconds/minutes/hours\n- **Cron expression jobs** β full cron syntax support\n- **One-time jobs** β execute at a specific datetime\n\nAll jobs can be toggled, triggered manually, or removed via the CLI.\n\n### MCP Integration\n\nConnect any MCP-compatible tool server and expose its tools directly to the agent. Define MCP servers under `tools.mcpServers` in your config. For example, connect [feishu-mcp](https://github.com/lichman0405/feishu-mcp) to bring Feishu collaboration capabilities (messages, calendar, tasks, documents) into the agent via a clean MCP interface.\n\nFor long-running MCP tools (e.g. scientific computing), FeatherFlow automatically sends periodic heartbeat progress messages to the user so they know the task is still running. Configure `progressIntervalSeconds` per MCP server (default 15s) and increase `toolTimeout` for compute-heavy operations.\n\n### Task Queue Awareness\n\nWhen multiple users send messages simultaneously (e.g. in a group chat), FeatherFlow queues tasks and notifies each user of their queue position. Users see when their task starts processing and how many tasks are ahead. This is enabled by default via `channels.sendQueueNotifications`.\n\n---\n\n## Development\n\n### Prerequisites\n\n- Python 3.11+\n- Linux or macOS (recommended)\n\n### Run Tests\n\n```bash\nPYTHONPATH=. .venv/bin/pytest -q\n```\n\n### Lint\n\n```bash\n.venv/bin/ruff check .\n```\n\n---\n\n## Migration Guide\n\nIf upgrading from a previous version or migrating from `nanobot`:\n\n| Item | Old | New |\n|---|---|---|\n| Python package | `nanobot.*` | `featherflow.*` |\n| CLI command | `assistant` | `featherflow` |\n| Runtime directory | `~/.assistant` | `~/.featherflow` |\n| Workspace directory | `~/.assistant/workspace` | `~/.featherflow/workspace` |\n\nBackward-compatible fallbacks for old config and data paths are retained where possible.\n\n---\n\n## MCP Ecosystem\n\nFeatherFlow ships with seven domain-specific MCP servers as git submodules under `mcps/`.\nThey cover porous-material science, epitaxial surface analysis, PDF translation, and team collaboration.\n\n### Bundled MCP Servers\n\n| Name | Submodule | Python | Description |\n|---|---|---|---|\n| **zeopp** | `mcps/zeopp-backend` | 3.10+ | Zeo++ porous material geometry (volume, pore size, channels) |\n| **raspa2** | `mcps/raspa-mcp` | 3.11+ | RASPA2 molecular simulation β input templates, output parsing |\n| **mofstructure** | `mcps/mofstructure-mcp` | 3.9+ | MOF structural analysis β building blocks, topology, metal nodes |\n| **mofchecker** | `mcps/mofchecker-mcp` | **<3.11** | MOF structure validation β CIF integrity, geometry defects |\n| **miqrophi** | `mcps/miqrophi-mcp` | 3.10+ | Epitaxial lattice matching β CIF surface analysis, substrate screening, strain calculation |\n| **pdf2zh** | `mcps/pdftranslate-mcp` | 3.10β3.12 | PDF paper translation preserving LaTeX layout (needs OpenAI key) |\n| **feishu** | `mcps/feishu-mcp` | 3.11+ | Feishu/Lark β messaging, docs, tasks (needs App ID & Secret) |\n\n### Setup\n\n**1. Clone with submodules** (one-time):\n\n```bash\ngit clone --recurse-submodules https://github.com/lichman0405/featherflow.git\n# or, if you already cloned without --recurse-submodules:\ngit submodule update --init --recursive\n```\n\n**2. Install Python venvs** for each MCP:\n\n```bash\nbash scripts/setup_mcps.sh\n```\n\nThe script uses [`uv`](https://docs.astral.sh/uv/) and pins the correct Python version per MCP\n(notably `mofchecker` requires Python 3.10; `pdf2zh` requires β€3.12).\n\n**3. Register MCPs with featherflow**:\n\n```bash\nbash scripts/configure_mcps.sh\n```\n\nThis calls `featherflow config mcp add` for every server with recommended timeouts and lazy-mode settings.\n\n**4. Add credentials** for the two servers that need them β open `~/.featherflow/config.json` and fill in:\n\n```jsonc\n\"tools\": {\n \"mcpServers\": {\n \"pdf2zh\": {\n \"env\": {\n \"OPENAI_BASE_URL\": \"https://api.openai.com/v1\",\n \"OPENAI_API_KEY\": \"sk-...\",\n \"OPENAI_MODEL\": \"gpt-4o\"\n }\n },\n \"feishu\": {\n \"env\": {\n \"FEISHU_APP_ID\": \"cli_...\",\n \"FEISHU_APP_SECRET\": \"...\"\n }\n }\n }\n}\n```\n\n> **Security note**: MCP subprocesses launched via the stdio transport inherit only a minimal environment\n> (`HOME`, `PATH`, `SHELL`, `USER`, `TERM`, `LOGNAME`) β your LLM provider API keys are never exposed\n> to MCP servers unless you explicitly add them to `cfg.env` as shown above.\n\n---\n\n## Documentation Index\n\n### Root Documents\n\n- [README.md](README.md)\n- [CHANGELOG.md](CHANGELOG.md)\n- [CONTRIBUTING.md](CONTRIBUTING.md)\n\n### Project Docs (`docs/`)\n\n- [docs/API.md](docs/API.md)\n- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)\n- [docs/DEVELOPER_GUIDE.md](docs/DEVELOPER_GUIDE.md)\n- [docs/RAM_FIRST_MEMORY_CHECKPOINT.md](docs/RAM_FIRST_MEMORY_CHECKPOINT.md)\n- [docs/SECURITY.md](docs/SECURITY.md)\n- [docs/SECURITY_IMPROVEMENTS.md](docs/SECURITY_IMPROVEMENTS.md)\n- [docs/SELF_DEVELOPMENT.md](docs/SELF_DEVELOPMENT.md)\n\n### Scripts (`scripts/`)\n\n- [scripts/setup_mcps.sh](scripts/setup_mcps.sh) β Create isolated Python venvs for all bundled MCP servers\n- [scripts/configure_mcps.sh](scripts/configure_mcps.sh) β Register all bundled MCPs into `~/.featherflow/config.json`\n\n### Skills Docs (`featherflow/skills/`)\n\n- [featherflow/skills/README.md](featherflow/skills/README.md)\n- [featherflow/skills/cron/SKILL.md](featherflow/skills/cron/SKILL.md)\n- [featherflow/skills/feishu-report/SKILL.md](featherflow/skills/feishu-report/SKILL.md)\n- [featherflow/skills/github/SKILL.md](featherflow/skills/github/SKILL.md)\n- [featherflow/skills/memory/SKILL.md](featherflow/skills/memory/SKILL.md)\n- [featherflow/skills/paper-research/SKILL.md](featherflow/skills/paper-research/SKILL.md)\n- [featherflow/skills/skill-creator/SKILL.md](featherflow/skills/skill-creator/SKILL.md)\n- [featherflow/skills/summarize/SKILL.md](featherflow/skills/summarize/SKILL.md)\n- [featherflow/skills/tmux/SKILL.md](featherflow/skills/tmux/SKILL.md)\n- [featherflow/skills/weather/SKILL.md](featherflow/skills/weather/SKILL.md)\n- [featherflow/skills/workspace-cleanup/SKILL.md](featherflow/skills/workspace-cleanup/SKILL.md)\n\n### Template Docs (`featherflow/templates/`)\n\n- [featherflow/templates/AGENTS.md](featherflow/templates/AGENTS.md)\n- [featherflow/templates/HEARTBEAT.md](featherflow/templates/HEARTBEAT.md)\n- [featherflow/templates/SOUL.md](featherflow/templates/SOUL.md)\n- [featherflow/templates/TOOLS.md](featherflow/templates/TOOLS.md)\n- [featherflow/templates/USER.md](featherflow/templates/USER.md)\n- [featherflow/templates/memory/MEMORY.md](featherflow/templates/memory/MEMORY.md)\n\n---\n\n## License\n\n[MIT](LICENSE)\n"}, "8ab05ab1278d0b5ce027b915abe7340bd148a4ad": {"t": 1785771703.2639484, "n": 20279, "h": "639e17c3bcd71ed1", "c": "# FeatherFlow\n\n\n πββ¬πͺΆ A lightweight, extensible personal AI agent framework for production automation and conversational workflows.\n
\n\n\n \n \n \n \n \n \n
\n\n---\n\n## Overview\n\nFeatherFlow is a compact AI agent runtime designed for developers who want a self-hosted, programmable assistant. It connects to any OpenAI-compatible LLM provider and exposes a rich toolset β file operations, shell execution, web search, scheduled tasks, sub-agents, and external MCP servers β all configurable via a single JSON file.\n\nFeatherFlow is a domain-focused evolution of the upstream [`nanobot`](https://github.com/HKUDS/nanobot) project. Full credit to the upstream team for the excellent engineering baseline in runtime design and tool abstraction.\n\n> **Reference baseline:** `nanobot` @ [`30361c9`](https://github.com/HKUDS/nanobot/commit/30361c9307f9014f49530d80abd5717bc97f554a) (2026-02-23)\n\n---\n\n## Features\n\n| Category | Capabilities |\n|---|---|\n| **LLM Providers** | OpenRouter, OpenAI, Anthropic, DeepSeek, Gemini, Groq, Moonshot, MiniMax, ZhipuAI, DashScope (Qwen), SiliconFlow, VolcEngine, AiHubMix, vLLM, Ollama, OpenAI Codex (OAuth), GitHub Copilot (OAuth), and any OpenAI-compatible endpoint |\n| **Built-in Tools** | File system, shell, web fetch/search, paper research (search/details/download), cron scheduler, sub-agent spawning |\n| **Channels** | Channel adapters exist for Feishu/Telegram/Discord/Slack/Email/QQ/DingTalk/MoChat (runtime wiring via config) |\n| **MCP Integration** | Connect any MCP-compatible tool server (e.g. [feishu-mcp](https://github.com/lichman0405/feishu-mcp)) |\n| **Memory** | RAM-first with snapshots, lesson extraction, and compact session history |\n| **Extensibility** | MCP server integration, skill files, custom provider plugins |\n| **CLI** | Interactive onboarding, agent chat, gateway mode, cron and memory management |\n\n---\n\n## Quick Start\n\n### Installation\n\n```bash\n# Clone the repository\ngit clone https://github.com/lichman0405/featherflow.git\ncd featherflow\n\n# Create and activate a virtual environment\npython3 -m venv .venv\nsource .venv/bin/activate\n\n# Install FeatherFlow\npip install --upgrade pip\npip install -e .\n\n# Verify\nfeatherflow --version\n```\n\n### First Run\n\n```bash\n# Interactive setup wizard β configures your provider, model, and identity\nfeatherflow onboard\n\n# Send a one-shot message\nfeatherflow agent -m \"hello\"\n\n# Start an interactive chat session\nfeatherflow agent\n\n# Launch the long-running gateway (channels + scheduled jobs)\nfeatherflow gateway\n```\n\n`featherflow onboard` now also supports:\n\n- Paper research tool configuration (`tools.papers` provider, API key, limits)\n\n---\n\n## Installation Options\n\n### With Dev Dependencies\n\n```bash\npip install -e '.[dev]'\n```\n\n### Docker (Recommended for Production)\n\n```bash\n# Start the gateway\ndocker compose up --build featherflow-gateway\n\n# Run a one-off CLI command in the container\ndocker compose --profile cli run --rm featherflow-cli status\n```\n\n**Runtime data directory mapping:**\n\n| Location | Path |\n|---|---|\n| Host | `~/.featherflow` |\n| Container | `/home/featherflow/.featherflow` |\n\n> **Security:** The container runs as unprivileged user `featherflow` (UID 1000) β not root. The gateway port (`18790`) is bound to `127.0.0.1` by default and is **not** exposed to the network. Use a reverse proxy (e.g. Nginx) to expose it externally.\n\n### Bare-Metal (Non-Docker) Deployment\n\nFor running the gateway directly on a Linux/macOS host as a long-running service:\n\n**1. Prepare configuration** (if not done already):\n\n```bash\n# Interactive setup β creates ~/.featherflow/config.json\nfeatherflow onboard\n\n# Verify the config\nfeatherflow status\n```\n\n**2. (Optional) Set up MCP servers:**\n\n```bash\nbash scripts/setup_mcps.sh # install isolated venvs\nbash scripts/configure_mcps.sh # register MCPs into config\n```\n\n**3. Run with systemd** (Linux, recommended):\n\nCreate `/etc/systemd/system/featherflow.service`:\n\n```ini\n[Unit]\nDescription=FeatherFlow AI Agent Gateway\nAfter=network.target\n\n[Service]\nType=simple\nUser=featherflow\nWorkingDirectory=/home/featherflow\nExecStart=/home/featherflow/.local/bin/featherflow gateway\nRestart=on-failure\nRestartSec=10\nEnvironment=HOME=/home/featherflow\n\n[Install]\nWantedBy=multi-user.target\n```\n\n```bash\nsudo systemctl daemon-reload\nsudo systemctl enable --now featherflow\nsudo journalctl -u featherflow -f # tail logs\n```\n\nOn macOS, use `launchd` or a process manager like `supervisord` instead.\n\n**4. Reverse proxy** (optional, for external access):\n\nThe gateway listens on `127.0.0.1:18790`. To expose it, place it behind Nginx:\n\n```nginx\nserver {\n listen 443 ssl;\n server_name featherflow.example.com;\n\n location / {\n proxy_pass http://127.0.0.1:18790;\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n }\n}\n```\n\n### Upgrading\n\n```bash\ncd featherflow\ngit pull --recurse-submodules\npip install -e . # reinstall core\nbash scripts/setup_mcps.sh # update MCP venvs\nbash scripts/configure_mcps.sh # re-register MCPs (idempotent)\n# then restart the gateway (systemctl restart featherflow / docker compose up --build)\n```\n\n> **Note:** The Docker image does **not** include MCP submodules β MCP servers run as separate stdio subprocesses on the host. When using Docker, mount or install MCP venvs on the host and configure `tools.mcpServers` commands to point at host-side interpreters, or run MCP servers as separate containers and use HTTP transport (`url` instead of `command`).\n\n---\n\n## Configuration\n\nFeatherFlow reads from `~/.featherflow/config.json`. The interactive wizard (`featherflow onboard`) can generate this file for you.\n\n**Default paths:**\n\n| Item | Path |\n|---|---|\n| Config file | `~/.featherflow/config.json` |\n| Workspace | `~/.featherflow/workspace` |\n\n### Configuration Skeleton\n\n```json\n{\n \"providers\": {\n \"openrouter\": {\n \"apiKey\": \"sk-or-v1-xxx\"\n }\n },\n \"agents\": {\n \"defaults\": {\n \"model\": \"anthropic/claude-opus-4-5\",\n \"name\": \"featherflow\",\n \"temperature\": 0.7\n }\n },\n \"channels\": {\n },\n \"tools\": {\n \"web\": {\n \"enabled\": true\n }\n },\n \"heartbeat\": {\n \"enabled\": true,\n \"intervalSeconds\": 1800\n }\n}\n```\n\n### Key Sections\n\n- **`providers`** β API keys, custom `apiBase` URLs, and optional `extraHeaders` (e.g. `APP-Code` for AiHubMix) for each LLM provider.\n- **`agents.defaults`** β Default model, temperature, `maxTokens`, `maxToolIterations`, `memoryWindow`, and agent identity (`name`, `workspace`).\n- **`agents.memory`** β Memory flush cadence (`flushEveryUpdates`, `flushIntervalSeconds`) and short-term window sizes.\n- **`agents.sessions`** β Session compaction thresholds (`compactThresholdMessages`, `compactThresholdBytes`, `compactKeepMessages`).\n- **`agents.selfImprovement`** β Lesson extraction settings: `enabled`, `maxLessonsInPrompt`, `minLessonConfidence`, `maxLessons`, `promotionEnabled`, etc.\n- **`channels`** β Channel configuration for each IM adapter; also controls `sendProgress` (stream text to channel), `sendToolHints` (stream tool-call hints), and `sendQueueNotifications` (notify users about task queue position).\n - **`channels.feishu.requireMentionInGroups`** β When `true` (default), the bot only responds to group messages where it is @mentioned. Private chats are unaffected.\n- **`gateway`** β HTTP gateway listen address (`host`, `port`; default `0.0.0.0:18790` for bare-metal runs). When using Docker Compose the port is bound to `127.0.0.1:18790` by default.\n- **`tools`** β Web/search/fetch behavior, paper research provider settings (`tools.papers`), shell execution policy (`tools.exec.timeout`), `restrictToWorkspace` flag, and MCP server definitions (`tools.mcpServers`).\n - **`tools.mcpServers..progressIntervalSeconds`** β Heartbeat interval (seconds) for long-running MCP tool calls. Set to `0` to disable. Default `15`.\n - **`tools.mcpServers..toolTimeout`** β Timeout in seconds before a tool call is cancelled. For scientific computing MCP servers (e.g. raspa, mofstructure), set to `300`β`600`. Default `30`.\n - **`tools.mcpServers..allowedTools`** β Optional allowlist of tool names. When non-empty, only the listed tools from this MCP server are registered. All others are silently dropped.\n - **`tools.mcpServers..deniedTools`** β Optional denylist of tool names. Any tool whose name appears here is never registered, regardless of `allowedTools`.\n- **`heartbeat`** β Periodic background prompts (`enabled`, `intervalSeconds`) for proactive agent behaviors.\n\n> **Security:** Config files are automatically saved with `0600` permissions (owner-read-only) to protect API keys. Set strict `allowFrom` lists before exposing to any channel. See [`docs/SECURITY.md`](docs/SECURITY.md) for full guidance.\n\n### Environment Variable Overrides\n\nEvery config field can be overridden at runtime via environment variables using the prefix `FEATHERFLOW_` and `__` as the nesting delimiter:\n\n```bash\n# Override the default model\nFEATHERFLOW_AGENTS__DEFAULTS__MODEL=deepseek/deepseek-chat featherflow agent\n\n# Inject an API key without editing config.json\nFEATHERFLOW_PROVIDERS__OPENROUTER__API_KEY=sk-or-v1-xxx featherflow gateway\n```\n\nThis is particularly useful in containerised deployments where secrets are injected as environment variables rather than mounted files.\n\n---\n\n## CLI Reference\n\n**Agent & Gateway**\n\n| Command | Description |\n|---|---|\n| `featherflow onboard` | Interactive setup wizard |\n| `featherflow agent` | Start an interactive chat session |\n| `featherflow agent -m \"\"` | Send a single prompt and exit |\n| `featherflow gateway` | Run the long-running gateway (channels + cron) |\n\n**Status & Diagnostics**\n\n| Command | Description |\n|---|---|\n| `featherflow status` | Show runtime and provider status |\n| `featherflow channels status` | Show channel connection status |\n\n**Memory Management**\n\n| Command | Description |\n|---|---|\n| `featherflow memory status` | Show memory snapshot and stats |\n| `featherflow memory flush` | Force-persist pending memory updates immediately |\n| `featherflow memory compact [--max-items N]` | Prune long-term snapshot to at most N items |\n| `featherflow memory list [--limit N] [--session S]` | Browse long-term snapshot entries |\n| `featherflow memory delete ` | Remove a snapshot entry by ID |\n| `featherflow memory lessons status` | Show self-improvement lesson stats |\n| `featherflow memory lessons list` | List lessons (filter by `--scope`, `--session`, `--limit`) |\n| `featherflow memory lessons enable ` | Re-enable a disabled lesson |\n| `featherflow memory lessons disable ` | Suppress a lesson from future prompts |\n| `featherflow memory lessons delete ` | Permanently remove a lesson |\n| `featherflow memory lessons compact [--max-lessons N]` | Prune lessons to at most N entries |\n| `featherflow memory lessons reset` | Wipe all lessons |\n\n**Session Management**\n\n| Command | Description |\n|---|---|\n| `featherflow session compact --session ` | Compact a single conversation session |\n| `featherflow session compact --all` | Compact all stored sessions |\n\n**Cron Scheduler**\n\n| Command | Description |\n|---|---|\n| `featherflow cron list` | List all scheduled jobs |\n| `featherflow cron add` | Add a new scheduled job |\n| `featherflow cron run ` | Trigger a job manually |\n| `featherflow cron enable ` | Enable a job |\n| `featherflow cron disable ` | Disable a job |\n| `featherflow cron remove ` | Remove a job permanently |\n\n**Configuration**\n\n| Command | Description |\n|---|---|\n| `featherflow config show` | Print all non-default config values |\n| `featherflow config provider ` | Set or update a provider's API key / base URL |\n| `featherflow config feishu` | One-shot Feishu channel + feishu-mcp setup |\n| `featherflow config pdf2zh` | Configure pdf2zh MCP server (auto-fills LLM credentials) |\n| `featherflow config mcp list` | List all configured MCP servers |\n| `featherflow config mcp add ` | Add or update an MCP server (stdio or HTTP) |\n| `featherflow config mcp remove ` | Remove an MCP server |\n\n**Providers**\n\n| Command | Description |\n|---|---|\n| `featherflow provider login openai-codex` | Authenticate with OpenAI Codex (OAuth) |\n| `featherflow provider login github-copilot` | Authenticate with GitHub Copilot (OAuth) |\n\n---\n\n## Core Capabilities\n\n### Memory & Self-Improvement\n\nFeatherFlow uses a RAM-first memory architecture:\n\n- **Session window** β unconsolidated recent context for fast recall\n- **Long-term snapshots** β periodic persistence with audit trails\n- **Lesson extraction** β automatically distills insights from user feedback and tool outcomes\n- **Configurable confidence thresholds** β controls promotion of lessons to long-term memory\n\n### Scheduled Tasks\n\nJobs can be defined as:\n\n- **Interval jobs** β run every N seconds/minutes/hours\n- **Cron expression jobs** β full cron syntax support\n- **One-time jobs** β execute at a specific datetime\n\nAll jobs can be toggled, triggered manually, or removed via the CLI.\n\n### MCP Integration\n\nConnect any MCP-compatible tool server and expose its tools directly to the agent. Define MCP servers under `tools.mcpServers` in your config. For example, connect [feishu-mcp](https://github.com/lichman0405/feishu-mcp) to bring Feishu collaboration capabilities (messages, calendar, tasks, documents) into the agent via a clean MCP interface.\n\nFor long-running MCP tools (e.g. scientific computing), FeatherFlow automatically sends periodic heartbeat progress messages to the user so they know the task is still running. Configure `progressIntervalSeconds` per MCP server (default 15s) and increase `toolTimeout` for compute-heavy operations.\n\n### Task Queue Awareness\n\nWhen multiple users send messages simultaneously (e.g. in a group chat), FeatherFlow queues tasks and notifies each user of their queue position. Users see when their task starts processing and how many tasks are ahead. This is enabled by default via `channels.sendQueueNotifications`.\n\n---\n\n## Development\n\n### Prerequisites\n\n- Python 3.11+\n- Linux or macOS (recommended)\n\n### Run Tests\n\n```bash\nPYTHONPATH=. .venv/bin/pytest -q\n```\n\n### Lint\n\n```bash\n.venv/bin/ruff check .\n```\n\n---\n\n## Migration Guide\n\nIf upgrading from a previous version or migrating from `nanobot`:\n\n| Item | Old | New |\n|---|---|---|\n| Python package | `nanobot.*` | `featherflow.*` |\n| CLI command | `assistant` | `featherflow` |\n| Runtime directory | `~/.assistant` | `~/.featherflow` |\n| Workspace directory | `~/.assistant/workspace` | `~/.featherflow/workspace` |\n\nBackward-compatible fallbacks for old config and data paths are retained where possible.\n\n---\n\n## MCP Ecosystem\n\nFeatherFlow ships with seven domain-specific MCP servers as git submodules under `mcps/`.\nThey cover porous-material science, epitaxial surface analysis, PDF translation, and team collaboration.\n\n### Bundled MCP Servers\n\n| Name | Submodule | Python | Description |\n|---|---|---|---|\n| **zeopp** | `mcps/zeopp-backend` | 3.10+ | Zeo++ porous material geometry (volume, pore size, channels) |\n| **raspa2** | `mcps/raspa-mcp` | 3.11+ | RASPA2 molecular simulation β input templates, output parsing |\n| **mofstructure** | `mcps/mofstructure-mcp` | 3.9+ | MOF structural analysis β building blocks, topology, metal nodes |\n| **mofchecker** | `mcps/mofchecker-mcp` | **<3.11** | MOF structure validation β CIF integrity, geometry defects |\n| **miqrophi** | `mcps/miqrophi-mcp` | 3.10+ | Epitaxial lattice matching β CIF surface analysis, substrate screening, strain calculation |\n| **pdf2zh** | `mcps/pdftranslate-mcp` | 3.10β3.12 | PDF paper translation preserving LaTeX layout (needs OpenAI key) |\n| **feishu** | `mcps/feishu-mcp` | 3.11+ | Feishu/Lark β messaging, docs, tasks (needs App ID & Secret) |\n\n### Setup\n\n**1. Clone with submodules** (one-time):\n\n```bash\ngit clone --recurse-submodules https://github.com/lichman0405/featherflow.git\n# or, if you already cloned without --recurse-submodules:\ngit submodule update --init --recursive\n```\n\n**2. Install Python venvs** for each MCP:\n\n```bash\nbash scripts/setup_mcps.sh\n```\n\nThe script uses [`uv`](https://docs.astral.sh/uv/) and pins the correct Python version per MCP\n(notably `mofchecker` requires Python 3.10; `pdf2zh` requires β€3.12).\n\n**3. Register MCPs with featherflow**:\n\n```bash\nbash scripts/configure_mcps.sh\n```\n\nThis calls `featherflow config mcp add` for every server with recommended timeouts and lazy-mode settings.\n\n**4. Add credentials** for the two servers that need them β open `~/.featherflow/config.json` and fill in:\n\n```jsonc\n\"tools\": {\n \"mcpServers\": {\n \"pdf2zh\": {\n \"env\": {\n \"OPENAI_BASE_URL\": \"https://api.openai.com/v1\",\n \"OPENAI_API_KEY\": \"sk-...\",\n \"OPENAI_MODEL\": \"gpt-4o\"\n }\n },\n \"feishu\": {\n \"env\": {\n \"FEISHU_APP_ID\": \"cli_...\",\n \"FEISHU_APP_SECRET\": \"...\"\n }\n }\n }\n}\n```\n\n> **Security note**: MCP subprocesses launched via the stdio transport inherit only a minimal environment\n> (`HOME`, `PATH`, `SHELL`, `USER`, `TERM`, `LOGNAME`) β your LLM provider API keys are never exposed\n> to MCP servers unless you explicitly add them to `cfg.env` as shown above.\n\n---\n\n## Documentation Index\n\n### Root Documents\n\n- [README.md](README.md)\n- [CHANGELOG.md](CHANGELOG.md)\n- [CONTRIBUTING.md](CONTRIBUTING.md)\n\n### Project Docs (`docs/`)\n\n- [docs/API.md](docs/API.md)\n- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)\n- [docs/DEVELOPER_GUIDE.md](docs/DEVELOPER_GUIDE.md)\n- [docs/RAM_FIRST_MEMORY_CHECKPOINT.md](docs/RAM_FIRST_MEMORY_CHECKPOINT.md)\n- [docs/SECURITY.md](docs/SECURITY.md)\n- [docs/SECURITY_IMPROVEMENTS.md](docs/SECURITY_IMPROVEMENTS.md)\n- [docs/SELF_DEVELOPMENT.md](docs/SELF_DEVELOPMENT.md)\n\n### Scripts (`scripts/`)\n\n- [scripts/setup_mcps.sh](scripts/setup_mcps.sh) β Create isolated Python venvs for all bundled MCP servers\n- [scripts/configure_mcps.sh](scripts/configure_mcps.sh) β Register all bundled MCPs into `~/.featherflow/config.json`\n\n### Skills Docs (`featherflow/skills/`)\n\n- [featherflow/skills/README.md](featherflow/skills/README.md)\n- [featherflow/skills/cron/SKILL.md](featherflow/skills/cron/SKILL.md)\n- [featherflow/skills/feishu-report/SKILL.md](featherflow/skills/feishu-report/SKILL.md)\n- [featherflow/skills/github/SKILL.md](featherflow/skills/github/SKILL.md)\n- [featherflow/skills/memory/SKILL.md](featherflow/skills/memory/SKILL.md)\n- [featherflow/skills/paper-research/SKILL.md](featherflow/skills/paper-research/SKILL.md)\n- [featherflow/skills/skill-creator/SKILL.md](featherflow/skills/skill-creator/SKILL.md)\n- [featherflow/skills/summarize/SKILL.md](featherflow/skills/summarize/SKILL.md)\n- [featherflow/skills/tmux/SKILL.md](featherflow/skills/tmux/SKILL.md)\n- [featherflow/skills/weather/SKILL.md](featherflow/skills/weather/SKILL.md)\n- [featherflow/skills/workspace-cleanup/SKILL.md](featherflow/skills/workspace-cleanup/SKILL.md)\n\n### Template Docs (`featherflow/templates/`)\n\n- [featherflow/templates/AGENTS.md](featherflow/templates/AGENTS.md)\n- [featherflow/templates/HEARTBEAT.md](featherflow/templates/HEARTBEAT.md)\n- [featherflow/templates/SOUL.md](featherflow/templates/SOUL.md)\n- [featherflow/templates/TOOLS.md](featherflow/templates/TOOLS.md)\n- [featherflow/templates/USER.md](featherflow/templates/USER.md)\n- [featherflow/templates/memory/MEMORY.md](featherflow/templates/memory/MEMORY.md)\n\n---\n\n## License\n\n[MIT](LICENSE)\n"}, "6f3b19829e7667cbde56454ad8e3af68b30a8d33": {"t": 1785771705.4211018, "n": 20079, "h": "5a4c88440e5eecea", "c": "# FeatherFlow\n\n\n πββ¬πͺΆ A lightweight, extensible personal AI agent framework for production automation and conversational workflows.\n
\n\n\n \n \n \n \n \n \n
\n\n---\n\n## Overview\n\nFeatherFlow is a compact AI agent runtime designed for developers who want a self-hosted, programmable assistant. It connects to any OpenAI-compatible LLM provider and exposes a rich toolset β file operations, shell execution, web search, scheduled tasks, sub-agents, and external MCP servers β all configurable via a single JSON file.\n\nFeatherFlow is a domain-focused evolution of the upstream [`nanobot`](https://github.com/HKUDS/nanobot) project. Full credit to the upstream team for the excellent engineering baseline in runtime design and tool abstraction.\n\n> **Reference baseline:** `nanobot` @ [`30361c9`](https://github.com/HKUDS/nanobot/commit/30361c9307f9014f49530d80abd5717bc97f554a) (2026-02-23)\n\n---\n\n## Features\n\n| Category | Capabilities |\n|---|---|\n| **LLM Providers** | OpenRouter, OpenAI, Anthropic, DeepSeek, Gemini, Groq, Moonshot, MiniMax, ZhipuAI, DashScope (Qwen), SiliconFlow, VolcEngine, AiHubMix, vLLM, Ollama, OpenAI Codex (OAuth), GitHub Copilot (OAuth), and any OpenAI-compatible endpoint |\n| **Built-in Tools** | File system, shell, web fetch/search, paper research (search/details/download), cron scheduler, sub-agent spawning |\n| **Channels** | Channel adapters exist for Feishu/Telegram/Discord/Slack/Email/QQ/DingTalk/MoChat (runtime wiring via config) |\n| **MCP Integration** | Connect any MCP-compatible tool server (e.g. [feishu-mcp](https://github.com/lichman0405/feishu-mcp)) |\n| **Memory** | RAM-first with snapshots, lesson extraction, and compact session history |\n| **Extensibility** | MCP server integration, skill files, custom provider plugins |\n| **CLI** | Interactive onboarding, agent chat, gateway mode, cron and memory management |\n\n---\n\n## Quick Start\n\n### Installation\n\n```bash\n# Clone the repository\ngit clone https://github.com/lichman0405/featherflow.git\ncd featherflow\n\n# Create and activate a virtual environment\npython3 -m venv .venv\nsource .venv/bin/activate\n\n# Install FeatherFlow\npip install --upgrade pip\npip install -e .\n\n# Verify\nfeatherflow --version\n```\n\n### First Run\n\n```bash\n# Interactive setup wizard β configures your provider, model, and identity\nfeatherflow onboard\n\n# Send a one-shot message\nfeatherflow agent -m \"hello\"\n\n# Start an interactive chat session\nfeatherflow agent\n\n# Launch the long-running gateway (channels + scheduled jobs)\nfeatherflow gateway\n```\n\n`featherflow onboard` now also supports:\n\n- Paper research tool configuration (`tools.papers` provider, API key, limits)\n\n---\n\n## Installation Options\n\n### With Dev Dependencies\n\n```bash\npip install -e '.[dev]'\n```\n\n### Docker (Recommended for Production)\n\n```bash\n# Start the gateway\ndocker compose up --build featherflow-gateway\n\n# Run a one-off CLI command in the container\ndocker compose --profile cli run --rm featherflow-cli status\n```\n\n**Runtime data directory mapping:**\n\n| Location | Path |\n|---|---|\n| Host | `~/.featherflow` |\n| Container | `/home/featherflow/.featherflow` |\n\n> **Security:** The container runs as unprivileged user `featherflow` (UID 1000) β not root. The gateway port (`18790`) is bound to `127.0.0.1` by default and is **not** exposed to the network. Use a reverse proxy (e.g. Nginx) to expose it externally.\n\n### Bare-Metal (Non-Docker) Deployment\n\nFor running the gateway directly on a Linux/macOS host as a long-running service:\n\n**1. Prepare configuration** (if not done already):\n\n```bash\n# Interactive setup β creates ~/.featherflow/config.json\nfeatherflow onboard\n\n# Verify the config\nfeatherflow status\n```\n\n**2. (Optional) Set up MCP servers:**\n\n```bash\nbash scripts/setup_mcps.sh # install isolated venvs\nbash scripts/configure_mcps.sh # register MCPs into config\n```\n\n**3. Run with systemd** (Linux, recommended):\n\nCreate `/etc/systemd/system/featherflow.service`:\n\n```ini\n[Unit]\nDescription=FeatherFlow AI Agent Gateway\nAfter=network.target\n\n[Service]\nType=simple\nUser=featherflow\nWorkingDirectory=/home/featherflow\nExecStart=/home/featherflow/.local/bin/featherflow gateway\nRestart=on-failure\nRestartSec=10\nEnvironment=HOME=/home/featherflow\n\n[Install]\nWantedBy=multi-user.target\n```\n\n```bash\nsudo systemctl daemon-reload\nsudo systemctl enable --now featherflow\nsudo journalctl -u featherflow -f # tail logs\n```\n\nOn macOS, use `launchd` or a process manager like `supervisord` instead.\n\n**4. Reverse proxy** (optional, for external access):\n\nThe gateway listens on `127.0.0.1:18790`. To expose it, place it behind Nginx:\n\n```nginx\nserver {\n listen 443 ssl;\n server_name featherflow.example.com;\n\n location / {\n proxy_pass http://127.0.0.1:18790;\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n }\n}\n```\n\n### Upgrading\n\n```bash\ncd featherflow\ngit pull --recurse-submodules\npip install -e . # reinstall core\nbash scripts/setup_mcps.sh # update MCP venvs\nbash scripts/configure_mcps.sh # re-register MCPs (idempotent)\n# then restart the gateway (systemctl restart featherflow / docker compose up --build)\n```\n\n> **Note:** The Docker image does **not** include MCP submodules β MCP servers run as separate stdio subprocesses on the host. When using Docker, mount or install MCP venvs on the host and configure `tools.mcpServers` commands to point at host-side interpreters, or run MCP servers as separate containers and use HTTP transport (`url` instead of `command`).\n\n---\n\n## Configuration\n\nFeatherFlow reads from `~/.featherflow/config.json`. The interactive wizard (`featherflow onboard`) can generate this file for you.\n\n**Default paths:**\n\n| Item | Path |\n|---|---|\n| Config file | `~/.featherflow/config.json` |\n| Workspace | `~/.featherflow/workspace` |\n\n### Configuration Skeleton\n\n```json\n{\n \"providers\": {\n \"openrouter\": {\n \"apiKey\": \"sk-or-v1-xxx\"\n }\n },\n \"agents\": {\n \"defaults\": {\n \"model\": \"anthropic/claude-opus-4-5\",\n \"name\": \"featherflow\",\n \"temperature\": 0.7\n }\n },\n \"channels\": {\n },\n \"tools\": {\n \"web\": {\n \"enabled\": true\n }\n },\n \"heartbeat\": {\n \"enabled\": true,\n \"intervalSeconds\": 1800\n }\n}\n```\n\n### Key Sections\n\n- **`providers`** β API keys, custom `apiBase` URLs, and optional `extraHeaders` (e.g. `APP-Code` for AiHubMix) for each LLM provider.\n- **`agents.defaults`** β Default model, temperature, `maxTokens`, `maxToolIterations`, `memoryWindow`, and agent identity (`name`, `workspace`).\n- **`agents.memory`** β Memory flush cadence (`flushEveryUpdates`, `flushIntervalSeconds`) and short-term window sizes.\n- **`agents.sessions`** β Session compaction thresholds (`compactThresholdMessages`, `compactThresholdBytes`, `compactKeepMessages`).\n- **`agents.selfImprovement`** β Lesson extraction settings: `enabled`, `maxLessonsInPrompt`, `minLessonConfidence`, `maxLessons`, `promotionEnabled`, etc.\n- **`channels`** β Channel configuration for each IM adapter; also controls `sendProgress` (stream text to channel), `sendToolHints` (stream tool-call hints), and `sendQueueNotifications` (notify users about task queue position).\n - **`channels.feishu.requireMentionInGroups`** β When `true` (default), the bot only responds to group messages where it is @mentioned. Private chats are unaffected.\n- **`gateway`** β HTTP gateway listen address (`host`, `port`; default `0.0.0.0:18790` for bare-metal runs). When using Docker Compose the port is bound to `127.0.0.1:18790` by default.\n- **`tools`** β Web/search/fetch behavior, paper research provider settings (`tools.papers`), shell execution policy (`tools.exec.timeout`), `restrictToWorkspace` flag, and MCP server definitions (`tools.mcpServers`).\n - **`tools.mcpServers..progressIntervalSeconds`** β Heartbeat interval (seconds) for long-running MCP tool calls. Set to `0` to disable. Default `15`.\n - **`tools.mcpServers..toolTimeout`** β Timeout in seconds before a tool call is cancelled. For scientific computing MCP servers (e.g. raspa, mofstructure), set to `300`β`600`. Default `30`.\n - **`tools.mcpServers..allowedTools`** β Optional allowlist of tool names. When non-empty, only the listed tools from this MCP server are registered. All others are silently dropped.\n - **`tools.mcpServers..deniedTools`** β Optional denylist of tool names. Any tool whose name appears here is never registered, regardless of `allowedTools`.\n- **`heartbeat`** β Periodic background prompts (`enabled`, `intervalSeconds`) for proactive agent behaviors.\n\n> **Security:** Config files are automatically saved with `0600` permissions (owner-read-only) to protect API keys. Set strict `allowFrom` lists before exposing to any channel. See [`docs/SECURITY.md`](docs/SECURITY.md) for full guidance.\n\n### Environment Variable Overrides\n\nEvery config field can be overridden at runtime via environment variables using the prefix `FEATHERFLOW_` and `__` as the nesting delimiter:\n\n```bash\n# Override the default model\nFEATHERFLOW_AGENTS__DEFAULTS__MODEL=deepseek/deepseek-chat featherflow agent\n\n# Inject an API key without editing config.json\nFEATHERFLOW_PROVIDERS__OPENROUTER__API_KEY=sk-or-v1-xxx featherflow gateway\n```\n\nThis is particularly useful in containerised deployments where secrets are injected as environment variables rather than mounted files.\n\n---\n\n## CLI Reference\n\n**Agent & Gateway**\n\n| Command | Description |\n|---|---|\n| `featherflow onboard` | Interactive setup wizard |\n| `featherflow agent` | Start an interactive chat session |\n| `featherflow agent -m \"\"` | Send a single prompt and exit |\n| `featherflow gateway` | Run the long-running gateway (channels + cron) |\n\n**Status & Diagnostics**\n\n| Command | Description |\n|---|---|\n| `featherflow status` | Show runtime and provider status |\n| `featherflow channels status` | Show channel connection status |\n\n**Memory Management**\n\n| Command | Description |\n|---|---|\n| `featherflow memory status` | Show memory snapshot and stats |\n| `featherflow memory flush` | Force-persist pending memory updates immediately |\n| `featherflow memory compact [--max-items N]` | Prune long-term snapshot to at most N items |\n| `featherflow memory list [--limit N] [--session S]` | Browse long-term snapshot entries |\n| `featherflow memory delete ` | Remove a snapshot entry by ID |\n| `featherflow memory lessons status` | Show self-improvement lesson stats |\n| `featherflow memory lessons list` | List lessons (filter by `--scope`, `--session`, `--limit`) |\n| `featherflow memory lessons enable ` | Re-enable a disabled lesson |\n| `featherflow memory lessons disable ` | Suppress a lesson from future prompts |\n| `featherflow memory lessons delete ` | Permanently remove a lesson |\n| `featherflow memory lessons compact [--max-lessons N]` | Prune lessons to at most N entries |\n| `featherflow memory lessons reset` | Wipe all lessons |\n\n**Session Management**\n\n| Command | Description |\n|---|---|\n| `featherflow session compact --session ` | Compact a single conversation session |\n| `featherflow session compact --all` | Compact all stored sessions |\n\n**Cron Scheduler**\n\n| Command | Description |\n|---|---|\n| `featherflow cron list` | List all scheduled jobs |\n| `featherflow cron add` | Add a new scheduled job |\n| `featherflow cron run ` | Trigger a job manually |\n| `featherflow cron enable ` | Enable a job |\n| `featherflow cron disable ` | Disable a job |\n| `featherflow cron remove ` | Remove a job permanently |\n\n**Configuration**\n\n| Command | Description |\n|---|---|\n| `featherflow config show` | Print all non-default config values |\n| `featherflow config provider ` | Set or update a provider's API key / base URL |\n| `featherflow config feishu` | One-shot Feishu channel + feishu-mcp setup |\n| `featherflow config pdf2zh` | Configure pdf2zh MCP server (auto-fills LLM credentials) |\n| `featherflow config mcp list` | List all configured MCP servers |\n| `featherflow config mcp add ` | Add or update an MCP server (stdio or HTTP) |\n| `featherflow config mcp remove ` | Remove an MCP server |\n\n**Providers**\n\n| Command | Description |\n|---|---|\n| `featherflow provider login openai-codex` | Authenticate with OpenAI Codex (OAuth) |\n| `featherflow provider login github-copilot` | Authenticate with GitHub Copilot (OAuth) |\n\n---\n\n## Core Capabilities\n\n### Memory & Self-Improvement\n\nFeatherFlow uses a RAM-first memory architecture:\n\n- **Session window** β unconsolidated recent context for fast recall\n- **Long-term snapshots** β periodic persistence with audit trails\n- **Lesson extraction** β automatically distills insights from user feedback and tool outcomes\n- **Configurable confidence thresholds** β controls promotion of lessons to long-term memory\n\n### Scheduled Tasks\n\nJobs can be defined as:\n\n- **Interval jobs** β run every N seconds/minutes/hours\n- **Cron expression jobs** β full cron syntax support\n- **One-time jobs** β execute at a specific datetime\n\nAll jobs can be toggled, triggered manually, or removed via the CLI.\n\n### MCP Integration\n\nConnect any MCP-compatible tool server and expose its tools directly to the agent. Define MCP servers under `tools.mcpServers` in your config. For example, connect [feishu-mcp](https://github.com/lichman0405/feishu-mcp) to bring Feishu collaboration capabilities (messages, calendar, tasks, documents) into the agent via a clean MCP interface.\n\nFor long-running MCP tools (e.g. scientific computing), FeatherFlow automatically sends periodic heartbeat progress messages to the user so they know the task is still running. Configure `progressIntervalSeconds` per MCP server (default 15s) and increase `toolTimeout` for compute-heavy operations.\n\n### Task Queue Awareness\n\nWhen multiple users send messages simultaneously (e.g. in a group chat), FeatherFlow queues tasks and notifies each user of their queue position. Users see when their task starts processing and how many tasks are ahead. This is enabled by default via `channels.sendQueueNotifications`.\n\n---\n\n## Development\n\n### Prerequisites\n\n- Python 3.11+\n- Linux or macOS (recommended)\n\n### Run Tests\n\n```bash\nPYTHONPATH=. .venv/bin/pytest -q\n```\n\n### Lint\n\n```bash\n.venv/bin/ruff check .\n```\n\n---\n\n## Migration Guide\n\nIf upgrading from a previous version or migrating from `nanobot`:\n\n| Item | Old | New |\n|---|---|---|\n| Python package | `nanobot.*` | `featherflow.*` |\n| CLI command | `assistant` | `featherflow` |\n| Runtime directory | `~/.assistant` | `~/.featherflow` |\n| Workspace directory | `~/.assistant/workspace` | `~/.featherflow/workspace` |\n\nBackward-compatible fallbacks for old config and data paths are retained where possible.\n\n---\n\n## MCP Ecosystem\n\nFeatherFlow ships with seven domain-specific MCP servers as git submodules under `mcps/`.\nThey cover porous-material science, epitaxial surface analysis, PDF translation, and team collaboration.\n\n### Bundled MCP Servers\n\n| Name | Submodule | Python | Description |\n|---|---|---|---|\n| **zeopp** | `mcps/zeopp-backend` | 3.10+ | Zeo++ porous material geometry (volume, pore size, channels) |\n| **raspa2** | `mcps/raspa-mcp` | 3.11+ | RASPA2 molecular simulation β input templates, output parsing |\n| **mofstructure** | `mcps/mofstructure-mcp` | 3.9+ | MOF structural analysis β building blocks, topology, metal nodes |\n| **mofchecker** | `mcps/mofchecker-mcp` | **<3.11** | MOF structure validation β CIF integrity, geometry defects |\n| **miqrophi** | `mcps/miqrophi-mcp` | 3.10+ | Epitaxial lattice matching β CIF surface analysis, substrate screening, strain calculation |\n| **pdf2zh** | `mcps/pdftranslate-mcp` | 3.10β3.12 | PDF paper translation preserving LaTeX layout (needs OpenAI key) |\n| **feishu** | `mcps/feishu-mcp` | 3.11+ | Feishu/Lark β messaging, docs, tasks (needs App ID & Secret) |\n\n### Setup\n\n**1. Clone with submodules** (one-time):\n\n```bash\ngit clone --recurse-submodules https://github.com/lichman0405/featherflow.git\n# or, if you already cloned without --recurse-submodules:\ngit submodule update --init --recursive\n```\n\n**2. Install Python venvs** for each MCP:\n\n```bash\nbash scripts/setup_mcps.sh\n```\n\nThe script uses [`uv`](https://docs.astral.sh/uv/) and pins the correct Python version per MCP\n(notably `mofchecker` requires Python 3.10; `pdf2zh` requires β€3.12).\n\n**3. Register MCPs with featherflow**:\n\n```bash\nbash scripts/configure_mcps.sh\n```\n\nThis calls `featherflow config mcp add` for every server with recommended timeouts and lazy-mode settings.\n\n**4. Add credentials** for the two servers that need them β open `~/.featherflow/config.json` and fill in:\n\n```jsonc\n\"tools\": {\n \"mcpServers\": {\n \"pdf2zh\": {\n \"env\": {\n \"OPENAI_BASE_URL\": \"https://api.openai.com/v1\",\n \"OPENAI_API_KEY\": \"sk-...\",\n \"OPENAI_MODEL\": \"gpt-4o\"\n }\n },\n \"feishu\": {\n \"env\": {\n \"FEISHU_APP_ID\": \"cli_...\",\n \"FEISHU_APP_SECRET\": \"...\"\n }\n }\n }\n}\n```\n\n> **Security note**: MCP subprocesses launched via the stdio transport inherit only a minimal environment\n> (`HOME`, `PATH`, `SHELL`, `USER`, `TERM`, `LOGNAME`) β your LLM provider API keys are never exposed\n> to MCP servers unless you explicitly add them to `cfg.env` as shown above.\n\n---\n\n## Documentation Index\n\n### Root Documents\n\n- [README.md](README.md)\n- [CHANGELOG.md](CHANGELOG.md)\n- [CONTRIBUTING.md](CONTRIBUTING.md)\n\n### Project Docs (`docs/`)\n\n- [docs/API.md](docs/API.md)\n- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)\n- [docs/DEVELOPER_GUIDE.md](docs/DEVELOPER_GUIDE.md)\n- [docs/RAM_FIRST_MEMORY_CHECKPOINT.md](docs/RAM_FIRST_MEMORY_CHECKPOINT.md)\n- [docs/SECURITY.md](docs/SECURITY.md)\n- [docs/SECURITY_IMPROVEMENTS.md](docs/SECURITY_IMPROVEMENTS.md)\n- [docs/SELF_DEVELOPMENT.md](docs/SELF_DEVELOPMENT.md)\n\n### Scripts (`scripts/`)\n\n- [scripts/setup_mcps.sh](scripts/setup_mcps.sh) β Create isolated Python venvs for all bundled MCP servers\n- [scripts/configure_mcps.sh](scripts/configure_mcps.sh) β Register all bundled MCPs into `~/.featherflow/config.json`\n\n### Skills Docs (`featherflow/skills/`)\n\n- [featherflow/skills/README.md](featherflow/skills/README.md)\n- [featherflow/skills/clawhub/SKILL.md](featherflow/skills/clawhub/SKILL.md)\n- [featherflow/skills/cron/SKILL.md](featherflow/skills/cron/SKILL.md)\n- [featherflow/skills/github/SKILL.md](featherflow/skills/github/SKILL.md)\n- [featherflow/skills/memory/SKILL.md](featherflow/skills/memory/SKILL.md)\n- [featherflow/skills/skill-creator/SKILL.md](featherflow/skills/skill-creator/SKILL.md)\n- [featherflow/skills/summarize/SKILL.md](featherflow/skills/summarize/SKILL.md)\n- [featherflow/skills/tmux/SKILL.md](featherflow/skills/tmux/SKILL.md)\n- [featherflow/skills/weather/SKILL.md](featherflow/skills/weather/SKILL.md)\n\n### Template Docs (`featherflow/templates/`)\n\n- [featherflow/templates/AGENTS.md](featherflow/templates/AGENTS.md)\n- [featherflow/templates/HEARTBEAT.md](featherflow/templates/HEARTBEAT.md)\n- [featherflow/templates/SOUL.md](featherflow/templates/SOUL.md)\n- [featherflow/templates/TOOLS.md](featherflow/templates/TOOLS.md)\n- [featherflow/templates/USER.md](featherflow/templates/USER.md)\n- [featherflow/templates/memory/MEMORY.md](featherflow/templates/memory/MEMORY.md)\n\n---\n\n## License\n\n[MIT](LICENSE)\n"}, "1443914db4be46d1da84c9a0206d0c18f190ca73": {"t": 1785771706.8290436, "n": 20026, "h": "c998abbdd8c45f41", "c": "# FeatherFlow\n\n\n πββ¬πͺΆ A lightweight, extensible personal AI agent framework for production automation and conversational workflows.\n
\n\n\n \n \n \n \n \n \n
\n\n---\n\n## Overview\n\nFeatherFlow is a compact AI agent runtime designed for developers who want a self-hosted, programmable assistant. It connects to any OpenAI-compatible LLM provider and exposes a rich toolset β file operations, shell execution, web search, scheduled tasks, sub-agents, and external MCP servers β all configurable via a single JSON file.\n\nFeatherFlow is a domain-focused evolution of the upstream [`nanobot`](https://github.com/HKUDS/nanobot) project. Full credit to the upstream team for the excellent engineering baseline in runtime design and tool abstraction.\n\n> **Reference baseline:** `nanobot` @ [`30361c9`](https://github.com/HKUDS/nanobot/commit/30361c9307f9014f49530d80abd5717bc97f554a) (2026-02-23)\n\n---\n\n## Features\n\n| Category | Capabilities |\n|---|---|\n| **LLM Providers** | OpenRouter, OpenAI, Anthropic, DeepSeek, Gemini, Groq, Moonshot, MiniMax, ZhipuAI, DashScope (Qwen), SiliconFlow, VolcEngine, AiHubMix, vLLM, Ollama, OpenAI Codex (OAuth), GitHub Copilot (OAuth), and any OpenAI-compatible endpoint |\n| **Built-in Tools** | File system, shell, web fetch/search, paper research (search/details/download), cron scheduler, sub-agent spawning |\n| **Channels** | Channel adapters exist for Feishu/Telegram/Discord/Slack/Email/QQ/DingTalk/MoChat (runtime wiring via config) |\n| **MCP Integration** | Connect any MCP-compatible tool server (e.g. [feishu-mcp](https://github.com/lichman0405/feishu-mcp)) |\n| **Memory** | RAM-first with snapshots, lesson extraction, and compact session history |\n| **Extensibility** | MCP server integration, skill files, custom provider plugins |\n| **CLI** | Interactive onboarding, agent chat, gateway mode, cron and memory management |\n\n---\n\n## Quick Start\n\n### Installation\n\n```bash\n# Clone the repository\ngit clone https://github.com/lichman0405/featherflow.git\ncd featherflow\n\n# Create and activate a virtual environment\npython3 -m venv .venv\nsource .venv/bin/activate\n\n# Install FeatherFlow\npip install --upgrade pip\npip install -e .\n\n# Verify\nfeatherflow --version\n```\n\n### First Run\n\n```bash\n# Interactive setup wizard β configures your provider, model, and identity\nfeatherflow onboard\n\n# Send a one-shot message\nfeatherflow agent -m \"hello\"\n\n# Start an interactive chat session\nfeatherflow agent\n\n# Launch the long-running gateway (channels + scheduled jobs)\nfeatherflow gateway\n```\n\n`featherflow onboard` now also supports:\n\n- Paper research tool configuration (`tools.papers` provider, API key, limits)\n\n---\n\n## Installation Options\n\n### With Dev Dependencies\n\n```bash\npip install -e '.[dev]'\n```\n\n### Docker (Recommended for Production)\n\n```bash\n# Start the gateway\ndocker compose up --build featherflow-gateway\n\n# Run a one-off CLI command in the container\ndocker compose --profile cli run --rm featherflow-cli status\n```\n\n**Runtime data directory mapping:**\n\n| Location | Path |\n|---|---|\n| Host | `~/.featherflow` |\n| Container | `/home/featherflow/.featherflow` |\n\n> **Security:** The container runs as unprivileged user `featherflow` (UID 1000) β not root. The gateway port (`18790`) is bound to `127.0.0.1` by default and is **not** exposed to the network. Use a reverse proxy (e.g. Nginx) to expose it externally.\n\n### Bare-Metal (Non-Docker) Deployment\n\nFor running the gateway directly on a Linux/macOS host as a long-running service:\n\n**1. Prepare configuration** (if not done already):\n\n```bash\n# Interactive setup β creates ~/.featherflow/config.json\nfeatherflow onboard\n\n# Verify the config\nfeatherflow status\n```\n\n**2. (Optional) Set up MCP servers:**\n\n```bash\nbash scripts/setup_mcps.sh # install isolated venvs\nbash scripts/configure_mcps.sh # register MCPs into config\n```\n\n**3. Run with systemd** (Linux, recommended):\n\nCreate `/etc/systemd/system/featherflow.service`:\n\n```ini\n[Unit]\nDescription=FeatherFlow AI Agent Gateway\nAfter=network.target\n\n[Service]\nType=simple\nUser=featherflow\nWorkingDirectory=/home/featherflow\nExecStart=/home/featherflow/.local/bin/featherflow gateway\nRestart=on-failure\nRestartSec=10\nEnvironment=HOME=/home/featherflow\n\n[Install]\nWantedBy=multi-user.target\n```\n\n```bash\nsudo systemctl daemon-reload\nsudo systemctl enable --now featherflow\nsudo journalctl -u featherflow -f # tail logs\n```\n\nOn macOS, use `launchd` or a process manager like `supervisord` instead.\n\n**4. Reverse proxy** (optional, for external access):\n\nThe gateway listens on `127.0.0.1:18790`. To expose it, place it behind Nginx:\n\n```nginx\nserver {\n listen 443 ssl;\n server_name featherflow.example.com;\n\n location / {\n proxy_pass http://127.0.0.1:18790;\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n }\n}\n```\n\n### Upgrading\n\n```bash\ncd featherflow\ngit pull --recurse-submodules\npip install -e . # reinstall core\nbash scripts/setup_mcps.sh # update MCP venvs\nbash scripts/configure_mcps.sh # re-register MCPs (idempotent)\n# then restart the gateway (systemctl restart featherflow / docker compose up --build)\n```\n\n> **Note:** The Docker image does **not** include MCP submodules β MCP servers run as separate stdio subprocesses on the host. When using Docker, mount or install MCP venvs on the host and configure `tools.mcpServers` commands to point at host-side interpreters, or run MCP servers as separate containers and use HTTP transport (`url` instead of `command`).\n\n---\n\n## Configuration\n\nFeatherFlow reads from `~/.featherflow/config.json`. The interactive wizard (`featherflow onboard`) can generate this file for you.\n\n**Default paths:**\n\n| Item | Path |\n|---|---|\n| Config file | `~/.featherflow/config.json` |\n| Workspace | `~/.featherflow/workspace` |\n\n### Configuration Skeleton\n\n```json\n{\n \"providers\": {\n \"openrouter\": {\n \"apiKey\": \"sk-or-v1-xxx\"\n }\n },\n \"agents\": {\n \"defaults\": {\n \"model\": \"anthropic/claude-opus-4-5\",\n \"name\": \"featherflow\",\n \"temperature\": 0.7\n }\n },\n \"channels\": {\n },\n \"tools\": {\n \"web\": {\n \"enabled\": true\n }\n },\n \"heartbeat\": {\n \"enabled\": true,\n \"intervalSeconds\": 1800\n }\n}\n```\n\n### Key Sections\n\n- **`providers`** β API keys, custom `apiBase` URLs, and optional `extraHeaders` (e.g. `APP-Code` for AiHubMix) for each LLM provider.\n- **`agents.defaults`** β Default model, temperature, `maxTokens`, `maxToolIterations`, `memoryWindow`, and agent identity (`name`, `workspace`).\n- **`agents.memory`** β Memory flush cadence (`flushEveryUpdates`, `flushIntervalSeconds`) and short-term window sizes.\n- **`agents.sessions`** β Session compaction thresholds (`compactThresholdMessages`, `compactThresholdBytes`, `compactKeepMessages`).\n- **`agents.selfImprovement`** β Lesson extraction settings: `enabled`, `maxLessonsInPrompt`, `minLessonConfidence`, `maxLessons`, `promotionEnabled`, etc.\n- **`channels`** β Channel configuration for each IM adapter; also controls `sendProgress` (stream text to channel), `sendToolHints` (stream tool-call hints), and `sendQueueNotifications` (notify users about task queue position).\n - **`channels.feishu.requireMentionInGroups`** β When `true` (default), the bot only responds to group messages where it is @mentioned. Private chats are unaffected.\n- **`gateway`** β HTTP gateway listen address (`host`, `port`; default `0.0.0.0:18790` for bare-metal runs). When using Docker Compose the port is bound to `127.0.0.1:18790` by default.\n- **`tools`** β Web/search/fetch behavior, paper research provider settings (`tools.papers`), shell execution policy (`tools.exec.timeout`), `restrictToWorkspace` flag, and MCP server definitions (`tools.mcpServers`).\n - **`tools.mcpServers..progressIntervalSeconds`** β Heartbeat interval (seconds) for long-running MCP tool calls. Set to `0` to disable. Default `15`.\n - **`tools.mcpServers..toolTimeout`** β Timeout in seconds before a tool call is cancelled. For scientific computing MCP servers (e.g. raspa, mofstructure), set to `300`β`600`.\n - **`tools.mcpServers..allowedTools`** β Optional allowlist of tool names. When non-empty, only the listed tools from this MCP server are registered. All others are silently dropped.\n - **`tools.mcpServers..deniedTools`** β Optional denylist of tool names. Any tool whose name appears here is never registered, regardless of `allowedTools`.\n- **`heartbeat`** β Periodic background prompts (`enabled`, `intervalSeconds`) for proactive agent behaviors.\n\n> **Security:** Set file permissions to `0600` on your config file and configure strict `allowFrom` lists before exposing to any channel. See [`docs/SECURITY.md`](docs/SECURITY.md) for full guidance.\n\n### Environment Variable Overrides\n\nEvery config field can be overridden at runtime via environment variables using the prefix `FEATHERFLOW_` and `__` as the nesting delimiter:\n\n```bash\n# Override the default model\nFEATHERFLOW_AGENTS__DEFAULTS__MODEL=deepseek/deepseek-chat featherflow agent\n\n# Inject an API key without editing config.json\nFEATHERFLOW_PROVIDERS__OPENROUTER__API_KEY=sk-or-v1-xxx featherflow gateway\n```\n\nThis is particularly useful in containerised deployments where secrets are injected as environment variables rather than mounted files.\n\n---\n\n## CLI Reference\n\n**Agent & Gateway**\n\n| Command | Description |\n|---|---|\n| `featherflow onboard` | Interactive setup wizard |\n| `featherflow agent` | Start an interactive chat session |\n| `featherflow agent -m \"\"` | Send a single prompt and exit |\n| `featherflow gateway` | Run the long-running gateway (channels + cron) |\n\n**Status & Diagnostics**\n\n| Command | Description |\n|---|---|\n| `featherflow status` | Show runtime and provider status |\n| `featherflow channels status` | Show channel connection status |\n\n**Memory Management**\n\n| Command | Description |\n|---|---|\n| `featherflow memory status` | Show memory snapshot and stats |\n| `featherflow memory flush` | Force-persist pending memory updates immediately |\n| `featherflow memory compact [--max-items N]` | Prune long-term snapshot to at most N items |\n| `featherflow memory list [--limit N] [--session S]` | Browse long-term snapshot entries |\n| `featherflow memory delete ` | Remove a snapshot entry by ID |\n| `featherflow memory lessons status` | Show self-improvement lesson stats |\n| `featherflow memory lessons list` | List lessons (filter by `--scope`, `--session`, `--limit`) |\n| `featherflow memory lessons enable ` | Re-enable a disabled lesson |\n| `featherflow memory lessons disable ` | Suppress a lesson from future prompts |\n| `featherflow memory lessons delete ` | Permanently remove a lesson |\n| `featherflow memory lessons compact [--max-lessons N]` | Prune lessons to at most N entries |\n| `featherflow memory lessons reset` | Wipe all lessons |\n\n**Session Management**\n\n| Command | Description |\n|---|---|\n| `featherflow session compact --session ` | Compact a single conversation session |\n| `featherflow session compact --all` | Compact all stored sessions |\n\n**Cron Scheduler**\n\n| Command | Description |\n|---|---|\n| `featherflow cron list` | List all scheduled jobs |\n| `featherflow cron add` | Add a new scheduled job |\n| `featherflow cron run ` | Trigger a job manually |\n| `featherflow cron enable ` | Enable a job |\n| `featherflow cron disable ` | Disable a job |\n| `featherflow cron remove ` | Remove a job permanently |\n\n**Configuration**\n\n| Command | Description |\n|---|---|\n| `featherflow config show` | Print all non-default config values |\n| `featherflow config provider ` | Set or update a provider's API key / base URL |\n| `featherflow config feishu` | One-shot Feishu channel + feishu-mcp setup |\n| `featherflow config pdf2zh` | Configure pdf2zh MCP server (auto-fills LLM credentials) |\n| `featherflow config mcp list` | List all configured MCP servers |\n| `featherflow config mcp add ` | Add or update an MCP server (stdio or HTTP) |\n| `featherflow config mcp remove ` | Remove an MCP server |\n\n**Providers**\n\n| Command | Description |\n|---|---|\n| `featherflow provider login openai-codex` | Authenticate with OpenAI Codex (OAuth) |\n| `featherflow provider login github-copilot` | Authenticate with GitHub Copilot (OAuth) |\n\n---\n\n## Core Capabilities\n\n### Memory & Self-Improvement\n\nFeatherFlow uses a RAM-first memory architecture:\n\n- **Session window** β unconsolidated recent context for fast recall\n- **Long-term snapshots** β periodic persistence with audit trails\n- **Lesson extraction** β automatically distills insights from user feedback and tool outcomes\n- **Configurable confidence thresholds** β controls promotion of lessons to long-term memory\n\n### Scheduled Tasks\n\nJobs can be defined as:\n\n- **Interval jobs** β run every N seconds/minutes/hours\n- **Cron expression jobs** β full cron syntax support\n- **One-time jobs** β execute at a specific datetime\n\nAll jobs can be toggled, triggered manually, or removed via the CLI.\n\n### MCP Integration\n\nConnect any MCP-compatible tool server and expose its tools directly to the agent. Define MCP servers under `tools.mcpServers` in your config. For example, connect [feishu-mcp](https://github.com/lichman0405/feishu-mcp) to bring Feishu collaboration capabilities (messages, calendar, tasks, documents) into the agent via a clean MCP interface.\n\nFor long-running MCP tools (e.g. scientific computing), FeatherFlow automatically sends periodic heartbeat progress messages to the user so they know the task is still running. Configure `progressIntervalSeconds` per MCP server (default 15s) and increase `toolTimeout` for compute-heavy operations.\n\n### Task Queue Awareness\n\nWhen multiple users send messages simultaneously (e.g. in a group chat), FeatherFlow queues tasks and notifies each user of their queue position. Users see when their task starts processing and how many tasks are ahead. This is enabled by default via `channels.sendQueueNotifications`.\n\n---\n\n## Development\n\n### Prerequisites\n\n- Python 3.11+\n- Linux or macOS (recommended)\n\n### Run Tests\n\n```bash\nPYTHONPATH=. .venv/bin/pytest -q\n```\n\n### Lint\n\n```bash\n.venv/bin/ruff check .\n```\n\n---\n\n## Migration Guide\n\nIf upgrading from a previous version or migrating from `nanobot`:\n\n| Item | Old | New |\n|---|---|---|\n| Python package | `nanobot.*` | `featherflow.*` |\n| CLI command | `assistant` | `featherflow` |\n| Runtime directory | `~/.assistant` | `~/.featherflow` |\n| Workspace directory | `~/.assistant/workspace` | `~/.featherflow/workspace` |\n\nBackward-compatible fallbacks for old config and data paths are retained where possible.\n\n---\n\n## MCP Ecosystem\n\nFeatherFlow ships with seven domain-specific MCP servers as git submodules under `mcps/`.\nThey cover porous-material science, epitaxial surface analysis, PDF translation, and team collaboration.\n\n### Bundled MCP Servers\n\n| Name | Submodule | Python | Description |\n|---|---|---|---|\n| **zeopp** | `mcps/zeopp-backend` | 3.10+ | Zeo++ porous material geometry (volume, pore size, channels) |\n| **raspa2** | `mcps/raspa-mcp` | 3.11+ | RASPA2 molecular simulation β input templates, output parsing |\n| **mofstructure** | `mcps/mofstructure-mcp` | 3.9+ | MOF structural analysis β building blocks, topology, metal nodes |\n| **mofchecker** | `mcps/mofchecker-mcp` | **<3.11** | MOF structure validation β CIF integrity, geometry defects |\n| **miqrophi** | `mcps/miqrophi-mcp` | 3.10+ | Epitaxial lattice matching β CIF surface analysis, substrate screening, strain calculation |\n| **pdf2zh** | `mcps/pdftranslate-mcp` | 3.10β3.12 | PDF paper translation preserving LaTeX layout (needs OpenAI key) |\n| **feishu** | `mcps/feishu-mcp` | 3.11+ | Feishu/Lark β messaging, docs, tasks (needs App ID & Secret) |\n\n### Setup\n\n**1. Clone with submodules** (one-time):\n\n```bash\ngit clone --recurse-submodules https://github.com/lichman0405/featherflow.git\n# or, if you already cloned without --recurse-submodules:\ngit submodule update --init --recursive\n```\n\n**2. Install Python venvs** for each MCP:\n\n```bash\nbash scripts/setup_mcps.sh\n```\n\nThe script uses [`uv`](https://docs.astral.sh/uv/) and pins the correct Python version per MCP\n(notably `mofchecker` requires Python 3.10; `pdf2zh` requires β€3.12).\n\n**3. Register MCPs with featherflow**:\n\n```bash\nbash scripts/configure_mcps.sh\n```\n\nThis calls `featherflow config mcp add` for every server with recommended timeouts and lazy-mode settings.\n\n**4. Add credentials** for the two servers that need them β open `~/.featherflow/config.json` and fill in:\n\n```jsonc\n\"tools\": {\n \"mcpServers\": {\n \"pdf2zh\": {\n \"env\": {\n \"OPENAI_BASE_URL\": \"https://api.openai.com/v1\",\n \"OPENAI_API_KEY\": \"sk-...\",\n \"OPENAI_MODEL\": \"gpt-4o\"\n }\n },\n \"feishu\": {\n \"env\": {\n \"FEISHU_APP_ID\": \"cli_...\",\n \"FEISHU_APP_SECRET\": \"...\"\n }\n }\n }\n}\n```\n\n> **Security note**: MCP subprocesses launched via the stdio transport inherit only a minimal environment\n> (`HOME`, `PATH`, `SHELL`, `USER`, `TERM`, `LOGNAME`) β your LLM provider API keys are never exposed\n> to MCP servers unless you explicitly add them to `cfg.env` as shown above.\n\n---\n\n## Documentation Index\n\n### Root Documents\n\n- [README.md](README.md)\n- [CHANGELOG.md](CHANGELOG.md)\n- [CONTRIBUTING.md](CONTRIBUTING.md)\n\n### Project Docs (`docs/`)\n\n- [docs/API.md](docs/API.md)\n- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)\n- [docs/DEVELOPER_GUIDE.md](docs/DEVELOPER_GUIDE.md)\n- [docs/RAM_FIRST_MEMORY_CHECKPOINT.md](docs/RAM_FIRST_MEMORY_CHECKPOINT.md)\n- [docs/SECURITY.md](docs/SECURITY.md)\n- [docs/SECURITY_IMPROVEMENTS.md](docs/SECURITY_IMPROVEMENTS.md)\n- [docs/SELF_DEVELOPMENT.md](docs/SELF_DEVELOPMENT.md)\n\n### Scripts (`scripts/`)\n\n- [scripts/setup_mcps.sh](scripts/setup_mcps.sh) β Create isolated Python venvs for all bundled MCP servers\n- [scripts/configure_mcps.sh](scripts/configure_mcps.sh) β Register all bundled MCPs into `~/.featherflow/config.json`\n\n### Skills Docs (`featherflow/skills/`)\n\n- [featherflow/skills/README.md](featherflow/skills/README.md)\n- [featherflow/skills/clawhub/SKILL.md](featherflow/skills/clawhub/SKILL.md)\n- [featherflow/skills/cron/SKILL.md](featherflow/skills/cron/SKILL.md)\n- [featherflow/skills/github/SKILL.md](featherflow/skills/github/SKILL.md)\n- [featherflow/skills/memory/SKILL.md](featherflow/skills/memory/SKILL.md)\n- [featherflow/skills/skill-creator/SKILL.md](featherflow/skills/skill-creator/SKILL.md)\n- [featherflow/skills/summarize/SKILL.md](featherflow/skills/summarize/SKILL.md)\n- [featherflow/skills/tmux/SKILL.md](featherflow/skills/tmux/SKILL.md)\n- [featherflow/skills/weather/SKILL.md](featherflow/skills/weather/SKILL.md)\n\n### Template Docs (`featherflow/templates/`)\n\n- [featherflow/templates/AGENTS.md](featherflow/templates/AGENTS.md)\n- [featherflow/templates/HEARTBEAT.md](featherflow/templates/HEARTBEAT.md)\n- [featherflow/templates/SOUL.md](featherflow/templates/SOUL.md)\n- [featherflow/templates/TOOLS.md](featherflow/templates/TOOLS.md)\n- [featherflow/templates/USER.md](featherflow/templates/USER.md)\n- [featherflow/templates/memory/MEMORY.md](featherflow/templates/memory/MEMORY.md)\n\n---\n\n## License\n\n[MIT](LICENSE)\n"}, "c60093a66ae3b0ab34237b6df0ccc8e463c8f801": {"t": 1785771708.5843554, "n": 17627, "h": "97207ef8d0ab3a0f", "c": "# FeatherFlow\n\n\n πββ¬πͺΆ A lightweight, extensible personal AI agent framework for production automation and conversational workflows.\n
\n\n\n \n \n \n \n \n \n
\n\n---\n\n## Overview\n\nFeatherFlow is a compact AI agent runtime designed for developers who want a self-hosted, programmable assistant. It connects to any OpenAI-compatible LLM provider and exposes a rich toolset β file operations, shell execution, web search, scheduled tasks, sub-agents, and external MCP servers β all configurable via a single JSON file.\n\nFeatherFlow is a domain-focused evolution of the upstream [`nanobot`](https://github.com/HKUDS/nanobot) project. Full credit to the upstream team for the excellent engineering baseline in runtime design and tool abstraction.\n\n> **Reference baseline:** `nanobot` @ [`30361c9`](https://github.com/HKUDS/nanobot/commit/30361c9307f9014f49530d80abd5717bc97f554a) (2026-02-23)\n\n---\n\n## Features\n\n| Category | Capabilities |\n|---|---|\n| **LLM Providers** | OpenRouter, OpenAI, Anthropic, DeepSeek, Gemini, Groq, Moonshot, MiniMax, ZhipuAI, DashScope (Qwen), SiliconFlow, VolcEngine, AiHubMix, vLLM, Ollama, OpenAI Codex (OAuth), GitHub Copilot (OAuth), and any OpenAI-compatible endpoint |\n| **Built-in Tools** | File system, shell, web fetch/search, paper research (search/details/download), cron scheduler, sub-agent spawning |\n| **Channels** | Channel adapters exist for Feishu/Telegram/Discord/Slack/Email/QQ/DingTalk/MoChat (runtime wiring via config) |\n| **MCP Integration** | Connect any MCP-compatible tool server (e.g. [feishu-mcp](https://github.com/lichman0405/feishu-mcp)) |\n| **Memory** | RAM-first with snapshots, lesson extraction, and compact session history |\n| **Extensibility** | MCP server integration, skill files, custom provider plugins |\n| **CLI** | Interactive onboarding, agent chat, gateway mode, cron and memory management |\n\n---\n\n## Quick Start\n\n### Installation\n\n```bash\n# Clone the repository\ngit clone https://github.com/lichman0405/featherflow.git\ncd featherflow\n\n# Create and activate a virtual environment\npython3 -m venv .venv\nsource .venv/bin/activate\n\n# Install FeatherFlow\npip install --upgrade pip\npip install -e .\n\n# Verify\nfeatherflow --version\n```\n\n### First Run\n\n```bash\n# Interactive setup wizard β configures your provider, model, and identity\nfeatherflow onboard\n\n# Send a one-shot message\nfeatherflow agent -m \"hello\"\n\n# Start an interactive chat session\nfeatherflow agent\n\n# Launch the long-running gateway (channels + scheduled jobs)\nfeatherflow gateway\n```\n\n`featherflow onboard` now also supports:\n\n- Paper research tool configuration (`tools.papers` provider, API key, limits)\n\n---\n\n## Installation Options\n\n### With Dev Dependencies\n\n```bash\npip install -e '.[dev]'\n```\n\n### Docker (Recommended for Production)\n\n```bash\n# Start the gateway\ndocker compose up --build featherflow-gateway\n\n# Run a one-off CLI command in the container\ndocker compose --profile cli run --rm featherflow-cli status\n```\n\n**Runtime data directory mapping:**\n\n| Location | Path |\n|---|---|\n| Host | `~/.featherflow` |\n| Container | `/home/featherflow/.featherflow` |\n\n> **Security:** The container runs as unprivileged user `featherflow` (UID 1000) β not root. The gateway port (`18790`) is bound to `127.0.0.1` by default and is **not** exposed to the network. Use a reverse proxy (e.g. Nginx) to expose it externally.\n\n---\n\n## Configuration\n\nFeatherFlow reads from `~/.featherflow/config.json`. The interactive wizard (`featherflow onboard`) can generate this file for you.\n\n**Default paths:**\n\n| Item | Path |\n|---|---|\n| Config file | `~/.featherflow/config.json` |\n| Workspace | `~/.featherflow/workspace` |\n\n### Configuration Skeleton\n\n```json\n{\n \"providers\": {\n \"openrouter\": {\n \"apiKey\": \"sk-or-v1-xxx\"\n }\n },\n \"agents\": {\n \"defaults\": {\n \"model\": \"anthropic/claude-opus-4-5\",\n \"name\": \"featherflow\",\n \"temperature\": 0.7\n }\n },\n \"channels\": {\n },\n \"tools\": {\n \"web\": {\n \"enabled\": true\n }\n },\n \"heartbeat\": {\n \"enabled\": true,\n \"intervalSeconds\": 1800\n }\n}\n```\n\n### Key Sections\n\n- **`providers`** β API keys, custom `apiBase` URLs, and optional `extraHeaders` (e.g. `APP-Code` for AiHubMix) for each LLM provider.\n- **`agents.defaults`** β Default model, temperature, `maxTokens`, `maxToolIterations`, `memoryWindow`, and agent identity (`name`, `workspace`).\n- **`agents.memory`** β Memory flush cadence (`flushEveryUpdates`, `flushIntervalSeconds`) and short-term window sizes.\n- **`agents.sessions`** β Session compaction thresholds (`compactThresholdMessages`, `compactThresholdBytes`, `compactKeepMessages`).\n- **`agents.selfImprovement`** β Lesson extraction settings: `enabled`, `maxLessonsInPrompt`, `minLessonConfidence`, `maxLessons`, `promotionEnabled`, etc.\n- **`channels`** β Channel configuration for each IM adapter; also controls `sendProgress` (stream text to channel), `sendToolHints` (stream tool-call hints), and `sendQueueNotifications` (notify users about task queue position).\n - **`channels.feishu.requireMentionInGroups`** β When `true` (default), the bot only responds to group messages where it is @mentioned. Private chats are unaffected.\n- **`gateway`** β HTTP gateway listen address (`host`, `port`; default `0.0.0.0:18790` for bare-metal runs). When using Docker Compose the port is bound to `127.0.0.1:18790` by default.\n- **`tools`** β Web/search/fetch behavior, paper research provider settings (`tools.papers`), shell execution policy (`tools.exec.timeout`), `restrictToWorkspace` flag, and MCP server definitions (`tools.mcpServers`).\n - **`tools.mcpServers..progressIntervalSeconds`** β Heartbeat interval (seconds) for long-running MCP tool calls. Set to `0` to disable. Default `15`.\n - **`tools.mcpServers..toolTimeout`** β Timeout in seconds before a tool call is cancelled. For scientific computing MCP servers (e.g. raspa, mofstructure), set to `300`β`600`.\n - **`tools.mcpServers..allowedTools`** β Optional allowlist of tool names. When non-empty, only the listed tools from this MCP server are registered. All others are silently dropped.\n - **`tools.mcpServers..deniedTools`** β Optional denylist of tool names. Any tool whose name appears here is never registered, regardless of `allowedTools`.\n- **`heartbeat`** β Periodic background prompts (`enabled`, `intervalSeconds`) for proactive agent behaviors.\n\n> **Security:** Set file permissions to `0600` on your config file and configure strict `allowFrom` lists before exposing to any channel. See [`docs/SECURITY.md`](docs/SECURITY.md) for full guidance.\n\n### Environment Variable Overrides\n\nEvery config field can be overridden at runtime via environment variables using the prefix `FEATHERFLOW_` and `__` as the nesting delimiter:\n\n```bash\n# Override the default model\nFEATHERFLOW_AGENTS__DEFAULTS__MODEL=deepseek/deepseek-chat featherflow agent\n\n# Inject an API key without editing config.json\nFEATHERFLOW_PROVIDERS__OPENROUTER__API_KEY=sk-or-v1-xxx featherflow gateway\n```\n\nThis is particularly useful in containerised deployments where secrets are injected as environment variables rather than mounted files.\n\n---\n\n## CLI Reference\n\n**Agent & Gateway**\n\n| Command | Description |\n|---|---|\n| `featherflow onboard` | Interactive setup wizard |\n| `featherflow agent` | Start an interactive chat session |\n| `featherflow agent -m \"\"` | Send a single prompt and exit |\n| `featherflow gateway` | Run the long-running gateway (channels + cron) |\n\n**Status & Diagnostics**\n\n| Command | Description |\n|---|---|\n| `featherflow status` | Show runtime and provider status |\n| `featherflow channels status` | Show channel connection status |\n\n**Memory Management**\n\n| Command | Description |\n|---|---|\n| `featherflow memory status` | Show memory snapshot and stats |\n| `featherflow memory flush` | Force-persist pending memory updates immediately |\n| `featherflow memory compact [--max-items N]` | Prune long-term snapshot to at most N items |\n| `featherflow memory list [--limit N] [--session S]` | Browse long-term snapshot entries |\n| `featherflow memory delete ` | Remove a snapshot entry by ID |\n| `featherflow memory lessons status` | Show self-improvement lesson stats |\n| `featherflow memory lessons list` | List lessons (filter by `--scope`, `--session`, `--limit`) |\n| `featherflow memory lessons enable ` | Re-enable a disabled lesson |\n| `featherflow memory lessons disable ` | Suppress a lesson from future prompts |\n| `featherflow memory lessons delete ` | Permanently remove a lesson |\n| `featherflow memory lessons compact [--max-lessons N]` | Prune lessons to at most N entries |\n| `featherflow memory lessons reset` | Wipe all lessons |\n\n**Session Management**\n\n| Command | Description |\n|---|---|\n| `featherflow session compact --session ` | Compact a single conversation session |\n| `featherflow session compact --all` | Compact all stored sessions |\n\n**Cron Scheduler**\n\n| Command | Description |\n|---|---|\n| `featherflow cron list` | List all scheduled jobs |\n| `featherflow cron add` | Add a new scheduled job |\n| `featherflow cron run ` | Trigger a job manually |\n| `featherflow cron enable ` | Enable a job |\n| `featherflow cron disable ` | Disable a job |\n| `featherflow cron remove ` | Remove a job permanently |\n\n**Configuration**\n\n| Command | Description |\n|---|---|\n| `featherflow config show` | Print all non-default config values |\n| `featherflow config provider ` | Set or update a provider's API key / base URL |\n| `featherflow config feishu` | One-shot Feishu channel + feishu-mcp setup |\n| `featherflow config pdf2zh` | Configure pdf2zh MCP server (auto-fills LLM credentials) |\n| `featherflow config mcp list` | List all configured MCP servers |\n| `featherflow config mcp add ` | Add or update an MCP server (stdio or HTTP) |\n| `featherflow config mcp remove ` | Remove an MCP server |\n\n**Providers**\n\n| Command | Description |\n|---|---|\n| `featherflow provider login openai-codex` | Authenticate with OpenAI Codex (OAuth) |\n| `featherflow provider login github-copilot` | Authenticate with GitHub Copilot (OAuth) |\n\n---\n\n## Core Capabilities\n\n### Memory & Self-Improvement\n\nFeatherFlow uses a RAM-first memory architecture:\n\n- **Session window** β unconsolidated recent context for fast recall\n- **Long-term snapshots** β periodic persistence with audit trails\n- **Lesson extraction** β automatically distills insights from user feedback and tool outcomes\n- **Configurable confidence thresholds** β controls promotion of lessons to long-term memory\n\n### Scheduled Tasks\n\nJobs can be defined as:\n\n- **Interval jobs** β run every N seconds/minutes/hours\n- **Cron expression jobs** β full cron syntax support\n- **One-time jobs** β execute at a specific datetime\n\nAll jobs can be toggled, triggered manually, or removed via the CLI.\n\n### MCP Integration\n\nConnect any MCP-compatible tool server and expose its tools directly to the agent. Define MCP servers under `tools.mcpServers` in your config. For example, connect [feishu-mcp](https://github.com/lichman0405/feishu-mcp) to bring Feishu collaboration capabilities (messages, calendar, tasks, documents) into the agent via a clean MCP interface.\n\nFor long-running MCP tools (e.g. scientific computing), FeatherFlow automatically sends periodic heartbeat progress messages to the user so they know the task is still running. Configure `progressIntervalSeconds` per MCP server (default 15s) and increase `toolTimeout` for compute-heavy operations.\n\n### Task Queue Awareness\n\nWhen multiple users send messages simultaneously (e.g. in a group chat), FeatherFlow queues tasks and notifies each user of their queue position. Users see when their task starts processing and how many tasks are ahead. This is enabled by default via `channels.sendQueueNotifications`.\n\n---\n\n## Development\n\n### Prerequisites\n\n- Python 3.11+\n- Linux or macOS (recommended)\n\n### Run Tests\n\n```bash\nPYTHONPATH=. .venv/bin/pytest -q\n```\n\n### Lint\n\n```bash\n.venv/bin/ruff check .\n```\n\n---\n\n## Migration Guide\n\nIf upgrading from a previous version or migrating from `nanobot`:\n\n| Item | Old | New |\n|---|---|---|\n| Python package | `nanobot.*` | `featherflow.*` |\n| CLI command | `assistant` | `featherflow` |\n| Runtime directory | `~/.assistant` | `~/.featherflow` |\n| Workspace directory | `~/.assistant/workspace` | `~/.featherflow/workspace` |\n\nBackward-compatible fallbacks for old config and data paths are retained where possible.\n\n---\n\n## MCP Ecosystem\n\nFeatherFlow ships with six domain-specific MCP servers as git submodules under `mcps/`.\nThey cover porous-material simulation, PDF translation, and team collaboration.\n\n### Bundled MCP Servers\n\n| Name | Submodule | Python | Description |\n|---|---|---|---|\n| **zeopp** | `mcps/zeopp-backend` | 3.10+ | Zeo++ porous material geometry (volume, pore size, channels) |\n| **raspa2** | `mcps/raspa-mcp` | 3.11+ | RASPA2 molecular simulation β input templates, output parsing |\n| **mofstructure** | `mcps/mofstructure-mcp` | 3.9+ | MOF structural analysis β building blocks, topology, metal nodes |\n| **mofchecker** | `mcps/mofchecker-mcp` | **<3.11** | MOF structure validation β CIF integrity, geometry defects |\n| **pdf2zh** | `mcps/pdftranslate-mcp` | 3.10β3.12 | PDF paper translation preserving LaTeX layout (needs OpenAI key) |\n| **feishu** | `mcps/feishu-mcp` | 3.11+ | Feishu/Lark β messaging, docs, tasks (needs App ID & Secret) |\n\n### Setup\n\n**1. Clone with submodules** (one-time):\n\n```bash\ngit clone --recurse-submodules https://github.com/lichman0405/featherflow.git\n# or, if you already cloned without --recurse-submodules:\ngit submodule update --init --recursive\n```\n\n**2. Install Python venvs** for each MCP:\n\n```bash\nbash scripts/setup_mcps.sh\n```\n\nThe script uses [`uv`](https://docs.astral.sh/uv/) and pins the correct Python version per MCP\n(notably `mofchecker` requires Python 3.10; `pdf2zh` requires β€3.12).\n\n**3. Register MCPs with featherflow**:\n\n```bash\nbash scripts/configure_mcps.sh\n```\n\nThis calls `featherflow config mcp add` for every server with recommended timeouts and lazy-mode settings.\n\n**4. Add credentials** for the two servers that need them β open `~/.featherflow/config.json` and fill in:\n\n```jsonc\n\"tools\": {\n \"mcpServers\": {\n \"pdf2zh\": {\n \"env\": {\n \"OPENAI_BASE_URL\": \"https://api.openai.com/v1\",\n \"OPENAI_API_KEY\": \"sk-...\",\n \"OPENAI_MODEL\": \"gpt-4o\"\n }\n },\n \"feishu\": {\n \"env\": {\n \"FEISHU_APP_ID\": \"cli_...\",\n \"FEISHU_APP_SECRET\": \"...\"\n }\n }\n }\n}\n```\n\n> **Security note**: MCP subprocesses launched via the stdio transport inherit only a minimal environment\n> (`HOME`, `PATH`, `SHELL`, `USER`, `TERM`, `LOGNAME`) β your LLM provider API keys are never exposed\n> to MCP servers unless you explicitly add them to `cfg.env` as shown above.\n\n---\n\n## Documentation Index\n\n### Root Documents\n\n- [README.md](README.md)\n- [CHANGELOG.md](CHANGELOG.md)\n- [CONTRIBUTING.md](CONTRIBUTING.md)\n\n### Project Docs (`docs/`)\n\n- [docs/API.md](docs/API.md)\n- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)\n- [docs/DEVELOPER_GUIDE.md](docs/DEVELOPER_GUIDE.md)\n- [docs/RAM_FIRST_MEMORY_CHECKPOINT.md](docs/RAM_FIRST_MEMORY_CHECKPOINT.md)\n- [docs/SECURITY.md](docs/SECURITY.md)\n- [docs/SELF_DEVELOPMENT.md](docs/SELF_DEVELOPMENT.md)\n\n### Scripts (`scripts/`)\n\n- [scripts/setup_mcps.sh](scripts/setup_mcps.sh) β Create isolated Python venvs for all bundled MCP servers\n- [scripts/configure_mcps.sh](scripts/configure_mcps.sh) β Register all bundled MCPs into `~/.featherflow/config.json`\n\n### Skills Docs (`featherflow/skills/`)\n\n- [featherflow/skills/README.md](featherflow/skills/README.md)\n- [featherflow/skills/clawhub/SKILL.md](featherflow/skills/clawhub/SKILL.md)\n- [featherflow/skills/cron/SKILL.md](featherflow/skills/cron/SKILL.md)\n- [featherflow/skills/github/SKILL.md](featherflow/skills/github/SKILL.md)\n- [featherflow/skills/memory/SKILL.md](featherflow/skills/memory/SKILL.md)\n- [featherflow/skills/skill-creator/SKILL.md](featherflow/skills/skill-creator/SKILL.md)\n- [featherflow/skills/summarize/SKILL.md](featherflow/skills/summarize/SKILL.md)\n- [featherflow/skills/tmux/SKILL.md](featherflow/skills/tmux/SKILL.md)\n- [featherflow/skills/weather/SKILL.md](featherflow/skills/weather/SKILL.md)\n\n### Template Docs (`featherflow/templates/`)\n\n- [featherflow/templates/AGENTS.md](featherflow/templates/AGENTS.md)\n- [featherflow/templates/HEARTBEAT.md](featherflow/templates/HEARTBEAT.md)\n- [featherflow/templates/SOUL.md](featherflow/templates/SOUL.md)\n- [featherflow/templates/TOOLS.md](featherflow/templates/TOOLS.md)\n- [featherflow/templates/USER.md](featherflow/templates/USER.md)\n- [featherflow/templates/memory/MEMORY.md](featherflow/templates/memory/MEMORY.md)\n\n---\n\n## License\n\n[MIT](LICENSE)\n"}, "20ce164920bebf22f8e59222c5b92ff1973404d6": {"t": 1785771710.410071, "n": 14277, "h": "f508115abd6c962c", "c": "# FeatherFlow\n\n\n πββ¬πͺΆ A lightweight, extensible personal AI agent framework for production automation and conversational workflows.\n
\n\n\n \n \n \n \n \n \n
\n\n---\n\n## Overview\n\nFeatherFlow is a compact AI agent runtime designed for developers who want a self-hosted, programmable assistant. It connects to any OpenAI-compatible LLM provider and exposes a rich toolset β file operations, shell execution, web search, scheduled tasks, sub-agents, and external MCP servers β all configurable via a single JSON file.\n\nFeatherFlow is a domain-focused evolution of the upstream [`nanobot`](https://github.com/HKUDS/nanobot) project. Full credit to the upstream team for the excellent engineering baseline in runtime design and tool abstraction.\n\n> **Reference baseline:** `nanobot` @ [`30361c9`](https://github.com/HKUDS/nanobot/commit/30361c9307f9014f49530d80abd5717bc97f554a) (2026-02-23)\n\n---\n\n## Features\n\n| Category | Capabilities |\n|---|---|\n| **LLM Providers** | OpenRouter, OpenAI, Anthropic, DeepSeek, Gemini, Groq, Moonshot, MiniMax, ZhipuAI, DashScope (Qwen), SiliconFlow, VolcEngine, AiHubMix, vLLM, Ollama, OpenAI Codex (OAuth), GitHub Copilot (OAuth), and any OpenAI-compatible endpoint |\n| **Built-in Tools** | File system, shell, web fetch/search, paper research (search/details/download), cron scheduler, sub-agent spawning |\n| **Channels** | Channel adapters exist for Feishu/Telegram/Discord/Slack/Email/QQ/DingTalk/MoChat (runtime wiring via config) |\n| **MCP Integration** | Connect any MCP-compatible tool server (e.g. [feishu-mcp](https://github.com/lichman0405/feishu-mcp)) |\n| **Memory** | RAM-first with snapshots, lesson extraction, and compact session history |\n| **Extensibility** | MCP server integration, skill files, custom provider plugins |\n| **CLI** | Interactive onboarding, agent chat, gateway mode, cron and memory management |\n\n---\n\n## Quick Start\n\n### Installation\n\n```bash\n# Clone the repository\ngit clone https://github.com/lichman0405/featherflow.git\ncd featherflow\n\n# Create and activate a virtual environment\npython3 -m venv .venv\nsource .venv/bin/activate\n\n# Install FeatherFlow\npip install --upgrade pip\npip install -e .\n\n# Verify\nfeatherflow --version\n```\n\n### First Run\n\n```bash\n# Interactive setup wizard β configures your provider, model, and identity\nfeatherflow onboard\n\n# Send a one-shot message\nfeatherflow agent -m \"hello\"\n\n# Start an interactive chat session\nfeatherflow agent\n\n# Launch the long-running gateway (channels + scheduled jobs)\nfeatherflow gateway\n```\n\n`featherflow onboard` now also supports:\n\n- Paper research tool configuration (`tools.papers` provider, API key, limits)\n\n---\n\n## Installation Options\n\n### With Dev Dependencies\n\n```bash\npip install -e '.[dev]'\n```\n\n### Docker (Recommended for Production)\n\n```bash\n# Start the gateway\ndocker compose up --build featherflow-gateway\n\n# Run a one-off CLI command in the container\ndocker compose --profile cli run --rm featherflow-cli status\n```\n\n**Runtime data directory mapping:**\n\n| Location | Path |\n|---|---|\n| Host | `~/.featherflow` |\n| Container | `/root/.featherflow` |\n\n---\n\n## Configuration\n\nFeatherFlow reads from `~/.featherflow/config.json`. The interactive wizard (`featherflow onboard`) can generate this file for you.\n\n**Default paths:**\n\n| Item | Path |\n|---|---|\n| Config file | `~/.featherflow/config.json` |\n| Workspace | `~/.featherflow/workspace` |\n\n### Configuration Skeleton\n\n```json\n{\n \"providers\": {\n \"openrouter\": {\n \"apiKey\": \"sk-or-v1-xxx\"\n }\n },\n \"agents\": {\n \"defaults\": {\n \"model\": \"anthropic/claude-opus-4-5\",\n \"name\": \"featherflow\",\n \"temperature\": 0.7\n }\n },\n \"channels\": {\n },\n \"tools\": {\n \"web\": {\n \"enabled\": true\n }\n },\n \"heartbeat\": {\n \"enabled\": true,\n \"intervalSeconds\": 1800\n }\n}\n```\n\n### Key Sections\n\n- **`providers`** β API keys, custom `apiBase` URLs, and optional `extraHeaders` (e.g. `APP-Code` for AiHubMix) for each LLM provider.\n- **`agents.defaults`** β Default model, temperature, `maxTokens`, `maxToolIterations`, `memoryWindow`, and agent identity (`name`, `workspace`).\n- **`agents.memory`** β Memory flush cadence (`flushEveryUpdates`, `flushIntervalSeconds`) and short-term window sizes.\n- **`agents.sessions`** β Session compaction thresholds (`compactThresholdMessages`, `compactThresholdBytes`, `compactKeepMessages`).\n- **`agents.selfImprovement`** β Lesson extraction settings: `enabled`, `maxLessonsInPrompt`, `minLessonConfidence`, `maxLessons`, `promotionEnabled`, etc.\n- **`channels`** β Channel configuration for each IM adapter; also controls `sendProgress` (stream text to channel), `sendToolHints` (stream tool-call hints), and `sendQueueNotifications` (notify users about task queue position).\n - **`channels.feishu.requireMentionInGroups`** β When `true` (default), the bot only responds to group messages where it is @mentioned. Private chats are unaffected.\n- **`gateway`** β HTTP gateway listen address (`host`, `port`; default `0.0.0.0:18790`).\n- **`tools`** β Web/search/fetch behavior, paper research provider settings (`tools.papers`), shell execution policy (`tools.exec.timeout`), `restrictToWorkspace` flag, and MCP server definitions (`tools.mcpServers`).\n - **`tools.mcpServers..progressIntervalSeconds`** β Heartbeat interval (seconds) for long-running MCP tool calls. Set to `0` to disable. Default `15`.\n - **`tools.mcpServers..toolTimeout`** β Timeout in seconds before a tool call is cancelled. For scientific computing MCP servers (e.g. raspa, mofstructure), set to `300`β`600`.\n- **`heartbeat`** β Periodic background prompts (`enabled`, `intervalSeconds`) for proactive agent behaviors.\n\n> **Security:** Set file permissions to `0600` on your config file and configure strict `allowFrom` lists before exposing to any channel. See [`docs/SECURITY.md`](docs/SECURITY.md) for full guidance.\n\n### Environment Variable Overrides\n\nEvery config field can be overridden at runtime via environment variables using the prefix `FEATHERFLOW_` and `__` as the nesting delimiter:\n\n```bash\n# Override the default model\nFEATHERFLOW_AGENTS__DEFAULTS__MODEL=deepseek/deepseek-chat featherflow agent\n\n# Inject an API key without editing config.json\nFEATHERFLOW_PROVIDERS__OPENROUTER__API_KEY=sk-or-v1-xxx featherflow gateway\n```\n\nThis is particularly useful in containerised deployments where secrets are injected as environment variables rather than mounted files.\n\n---\n\n## CLI Reference\n\n**Agent & Gateway**\n\n| Command | Description |\n|---|---|\n| `featherflow onboard` | Interactive setup wizard |\n| `featherflow agent` | Start an interactive chat session |\n| `featherflow agent -m \"\"` | Send a single prompt and exit |\n| `featherflow gateway` | Run the long-running gateway (channels + cron) |\n\n**Status & Diagnostics**\n\n| Command | Description |\n|---|---|\n| `featherflow status` | Show runtime and provider status |\n| `featherflow channels status` | Show channel connection status |\n\n**Memory Management**\n\n| Command | Description |\n|---|---|\n| `featherflow memory status` | Show memory snapshot and stats |\n| `featherflow memory flush` | Force-persist pending memory updates immediately |\n| `featherflow memory compact [--max-items N]` | Prune long-term snapshot to at most N items |\n| `featherflow memory list [--limit N] [--session S]` | Browse long-term snapshot entries |\n| `featherflow memory delete ` | Remove a snapshot entry by ID |\n| `featherflow memory lessons status` | Show self-improvement lesson stats |\n| `featherflow memory lessons list` | List lessons (filter by `--scope`, `--session`, `--limit`) |\n| `featherflow memory lessons enable ` | Re-enable a disabled lesson |\n| `featherflow memory lessons disable ` | Suppress a lesson from future prompts |\n| `featherflow memory lessons delete ` | Permanently remove a lesson |\n| `featherflow memory lessons compact [--max-lessons N]` | Prune lessons to at most N entries |\n| `featherflow memory lessons reset` | Wipe all lessons |\n\n**Session Management**\n\n| Command | Description |\n|---|---|\n| `featherflow session compact --session ` | Compact a single conversation session |\n| `featherflow session compact --all` | Compact all stored sessions |\n\n**Cron Scheduler**\n\n| Command | Description |\n|---|---|\n| `featherflow cron list` | List all scheduled jobs |\n| `featherflow cron add` | Add a new scheduled job |\n| `featherflow cron run ` | Trigger a job manually |\n| `featherflow cron enable ` | Enable a job |\n| `featherflow cron disable ` | Disable a job |\n| `featherflow cron remove ` | Remove a job permanently |\n\n**Configuration**\n\n| Command | Description |\n|---|---|\n| `featherflow config show` | Print all non-default config values |\n| `featherflow config provider ` | Set or update a provider's API key / base URL |\n| `featherflow config feishu` | One-shot Feishu channel + feishu-mcp setup |\n| `featherflow config pdf2zh` | Configure pdf2zh MCP server (auto-fills LLM credentials) |\n| `featherflow config mcp list` | List all configured MCP servers |\n| `featherflow config mcp add ` | Add or update an MCP server (stdio or HTTP) |\n| `featherflow config mcp remove ` | Remove an MCP server |\n\n**Providers**\n\n| Command | Description |\n|---|---|\n| `featherflow provider login openai-codex` | Authenticate with OpenAI Codex (OAuth) |\n| `featherflow provider login github-copilot` | Authenticate with GitHub Copilot (OAuth) |\n\n---\n\n## Core Capabilities\n\n### Memory & Self-Improvement\n\nFeatherFlow uses a RAM-first memory architecture:\n\n- **Session window** β unconsolidated recent context for fast recall\n- **Long-term snapshots** β periodic persistence with audit trails\n- **Lesson extraction** β automatically distills insights from user feedback and tool outcomes\n- **Configurable confidence thresholds** β controls promotion of lessons to long-term memory\n\n### Scheduled Tasks\n\nJobs can be defined as:\n\n- **Interval jobs** β run every N seconds/minutes/hours\n- **Cron expression jobs** β full cron syntax support\n- **One-time jobs** β execute at a specific datetime\n\nAll jobs can be toggled, triggered manually, or removed via the CLI.\n\n### MCP Integration\n\nConnect any MCP-compatible tool server and expose its tools directly to the agent. Define MCP servers under `tools.mcpServers` in your config. For example, connect [feishu-mcp](https://github.com/lichman0405/feishu-mcp) to bring Feishu collaboration capabilities (messages, calendar, tasks, documents) into the agent via a clean MCP interface.\n\nFor long-running MCP tools (e.g. scientific computing), FeatherFlow automatically sends periodic heartbeat progress messages to the user so they know the task is still running. Configure `progressIntervalSeconds` per MCP server (default 15s) and increase `toolTimeout` for compute-heavy operations.\n\n### Task Queue Awareness\n\nWhen multiple users send messages simultaneously (e.g. in a group chat), FeatherFlow queues tasks and notifies each user of their queue position. Users see when their task starts processing and how many tasks are ahead. This is enabled by default via `channels.sendQueueNotifications`.\n\n---\n\n## Development\n\n### Prerequisites\n\n- Python 3.11+\n- Linux or macOS (recommended)\n\n### Run Tests\n\n```bash\nPYTHONPATH=. .venv/bin/pytest -q\n```\n\n### Lint\n\n```bash\n.venv/bin/ruff check .\n```\n\n---\n\n## Migration Guide\n\nIf upgrading from a previous version or migrating from `nanobot`:\n\n| Item | Old | New |\n|---|---|---|\n| Python package | `nanobot.*` | `featherflow.*` |\n| CLI command | `assistant` | `featherflow` |\n| Runtime directory | `~/.assistant` | `~/.featherflow` |\n| Workspace directory | `~/.assistant/workspace` | `~/.featherflow/workspace` |\n\nBackward-compatible fallbacks for old config and data paths are retained where possible.\n\n---\n\n## Documentation Index\n\n### Root Documents\n\n- [README.md](README.md)\n- [CHANGELOG.md](CHANGELOG.md)\n- [CONTRIBUTING.md](CONTRIBUTING.md)\n\n### Project Docs (`docs/`)\n\n- [docs/API.md](docs/API.md)\n- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)\n- [docs/DEVELOPER_GUIDE.md](docs/DEVELOPER_GUIDE.md)\n- [docs/RAM_FIRST_MEMORY_CHECKPOINT.md](docs/RAM_FIRST_MEMORY_CHECKPOINT.md)\n- [docs/SECURITY.md](docs/SECURITY.md)\n- [docs/SELF_DEVELOPMENT.md](docs/SELF_DEVELOPMENT.md)\n\n### Skills Docs (`featherflow/skills/`)\n\n- [featherflow/skills/README.md](featherflow/skills/README.md)\n- [featherflow/skills/clawhub/SKILL.md](featherflow/skills/clawhub/SKILL.md)\n- [featherflow/skills/cron/SKILL.md](featherflow/skills/cron/SKILL.md)\n- [featherflow/skills/github/SKILL.md](featherflow/skills/github/SKILL.md)\n- [featherflow/skills/memory/SKILL.md](featherflow/skills/memory/SKILL.md)\n- [featherflow/skills/skill-creator/SKILL.md](featherflow/skills/skill-creator/SKILL.md)\n- [featherflow/skills/summarize/SKILL.md](featherflow/skills/summarize/SKILL.md)\n- [featherflow/skills/tmux/SKILL.md](featherflow/skills/tmux/SKILL.md)\n- [featherflow/skills/weather/SKILL.md](featherflow/skills/weather/SKILL.md)\n\n### Template Docs (`featherflow/templates/`)\n\n- [featherflow/templates/AGENTS.md](featherflow/templates/AGENTS.md)\n- [featherflow/templates/HEARTBEAT.md](featherflow/templates/HEARTBEAT.md)\n- [featherflow/templates/SOUL.md](featherflow/templates/SOUL.md)\n- [featherflow/templates/TOOLS.md](featherflow/templates/TOOLS.md)\n- [featherflow/templates/USER.md](featherflow/templates/USER.md)\n- [featherflow/templates/memory/MEMORY.md](featherflow/templates/memory/MEMORY.md)\n\n---\n\n## License\n\n[MIT](LICENSE)\n"}, "6f194e3c189b1eebb962108a16d98925ee3e5fea": {"t": 1785771713.3943017, "n": 13084, "h": "489b053484a46553", "c": "# FeatherFlow\n\n\n πββ¬πͺΆ A lightweight, extensible personal AI agent framework for production automation and conversational workflows.\n
\n\n\n \n \n \n \n \n \n
\n\n---\n\n## Overview\n\nFeatherFlow is a compact AI agent runtime designed for developers who want a self-hosted, programmable assistant. It connects to any OpenAI-compatible LLM provider and exposes a rich toolset β file operations, shell execution, web search, scheduled tasks, sub-agents, and external MCP servers β all configurable via a single JSON file.\n\nFeatherFlow is a domain-focused evolution of the upstream [`nanobot`](https://github.com/HKUDS/nanobot) project. Full credit to the upstream team for the excellent engineering baseline in runtime design and tool abstraction.\n\n> **Reference baseline:** `nanobot` @ [`30361c9`](https://github.com/HKUDS/nanobot/commit/30361c9307f9014f49530d80abd5717bc97f554a) (2026-02-23)\n\n---\n\n## Features\n\n| Category | Capabilities |\n|---|---|\n| **LLM Providers** | OpenRouter, OpenAI, Anthropic, DeepSeek, Gemini, Groq, Moonshot, MiniMax, ZhipuAI, DashScope (Qwen), SiliconFlow, VolcEngine, AiHubMix, vLLM, Ollama, OpenAI Codex (OAuth), GitHub Copilot (OAuth), and any OpenAI-compatible endpoint |\n| **Built-in Tools** | File system, shell, web fetch/search, paper research (search/details/download), cron scheduler, sub-agent spawning |\n| **Channels** | Channel adapters exist for Feishu/Telegram/Discord/Slack/Email/QQ/DingTalk/MoChat (runtime wiring via config) |\n| **MCP Integration** | Connect any MCP-compatible tool server (e.g. [feishu-mcp](https://github.com/lichman0405/feishu-mcp)) |\n| **Memory** | RAM-first with snapshots, lesson extraction, and compact session history |\n| **Extensibility** | MCP server integration, skill files, custom provider plugins |\n| **CLI** | Interactive onboarding, agent chat, gateway mode, cron and memory management |\n\n---\n\n## Quick Start\n\n### Installation\n\n```bash\n# Clone the repository\ngit clone https://github.com/lichman0405/featherflow.git\ncd featherflow\n\n# Create and activate a virtual environment\npython3 -m venv .venv\nsource .venv/bin/activate\n\n# Install FeatherFlow\npip install --upgrade pip\npip install -e .\n\n# Verify\nfeatherflow --version\n```\n\n### First Run\n\n```bash\n# Interactive setup wizard β configures your provider, model, and identity\nfeatherflow onboard\n\n# Send a one-shot message\nfeatherflow agent -m \"hello\"\n\n# Start an interactive chat session\nfeatherflow agent\n\n# Launch the long-running gateway (channels + scheduled jobs)\nfeatherflow gateway\n```\n\n`featherflow onboard` now also supports:\n\n- Paper research tool configuration (`tools.papers` provider, API key, limits)\n\n---\n\n## Installation Options\n\n### With Dev Dependencies\n\n```bash\npip install -e '.[dev]'\n```\n\n### Docker (Recommended for Production)\n\n```bash\n# Start the gateway\ndocker compose up --build featherflow-gateway\n\n# Run a one-off CLI command in the container\ndocker compose --profile cli run --rm featherflow-cli status\n```\n\n**Runtime data directory mapping:**\n\n| Location | Path |\n|---|---|\n| Host | `~/.featherflow` |\n| Container | `/root/.featherflow` |\n\n---\n\n## Configuration\n\nFeatherFlow reads from `~/.featherflow/config.json`. The interactive wizard (`featherflow onboard`) can generate this file for you.\n\n**Default paths:**\n\n| Item | Path |\n|---|---|\n| Config file | `~/.featherflow/config.json` |\n| Workspace | `~/.featherflow/workspace` |\n\n### Configuration Skeleton\n\n```json\n{\n \"providers\": {\n \"openrouter\": {\n \"apiKey\": \"sk-or-v1-xxx\"\n }\n },\n \"agents\": {\n \"defaults\": {\n \"model\": \"anthropic/claude-opus-4-5\",\n \"name\": \"featherflow\",\n \"temperature\": 0.7\n }\n },\n \"channels\": {\n },\n \"tools\": {\n \"web\": {\n \"enabled\": true\n }\n },\n \"heartbeat\": {\n \"enabled\": true,\n \"intervalSeconds\": 1800\n }\n}\n```\n\n### Key Sections\n\n- **`providers`** β API keys, custom `apiBase` URLs, and optional `extraHeaders` (e.g. `APP-Code` for AiHubMix) for each LLM provider.\n- **`agents.defaults`** β Default model, temperature, `maxTokens`, `maxToolIterations`, `memoryWindow`, and agent identity (`name`, `workspace`).\n- **`agents.memory`** β Memory flush cadence (`flushEveryUpdates`, `flushIntervalSeconds`) and short-term window sizes.\n- **`agents.sessions`** β Session compaction thresholds (`compactThresholdMessages`, `compactThresholdBytes`, `compactKeepMessages`).\n- **`agents.selfImprovement`** β Lesson extraction settings: `enabled`, `maxLessonsInPrompt`, `minLessonConfidence`, `maxLessons`, `promotionEnabled`, etc.\n- **`channels`** β Channel configuration for each IM adapter; also controls `sendProgress` (stream text to channel) and `sendToolHints` (stream tool-call hints).\n- **`gateway`** β HTTP gateway listen address (`host`, `port`; default `0.0.0.0:18790`).\n- **`tools`** β Web/search/fetch behavior, paper research provider settings (`tools.papers`), shell execution policy (`tools.exec.timeout`), `restrictToWorkspace` flag, and MCP server definitions (`tools.mcpServers`).\n- **`heartbeat`** β Periodic background prompts (`enabled`, `intervalSeconds`) for proactive agent behaviors.\n\n> **Security:** Set file permissions to `0600` on your config file and configure strict `allowFrom` lists before exposing to any channel. See [`docs/SECURITY.md`](docs/SECURITY.md) for full guidance.\n\n### Environment Variable Overrides\n\nEvery config field can be overridden at runtime via environment variables using the prefix `FEATHERFLOW_` and `__` as the nesting delimiter:\n\n```bash\n# Override the default model\nFEATHERFLOW_AGENTS__DEFAULTS__MODEL=deepseek/deepseek-chat featherflow agent\n\n# Inject an API key without editing config.json\nFEATHERFLOW_PROVIDERS__OPENROUTER__API_KEY=sk-or-v1-xxx featherflow gateway\n```\n\nThis is particularly useful in containerised deployments where secrets are injected as environment variables rather than mounted files.\n\n---\n\n## CLI Reference\n\n**Agent & Gateway**\n\n| Command | Description |\n|---|---|\n| `featherflow onboard` | Interactive setup wizard |\n| `featherflow agent` | Start an interactive chat session |\n| `featherflow agent -m \"\"` | Send a single prompt and exit |\n| `featherflow gateway` | Run the long-running gateway (channels + cron) |\n\n**Status & Diagnostics**\n\n| Command | Description |\n|---|---|\n| `featherflow status` | Show runtime and provider status |\n| `featherflow channels status` | Show channel connection status |\n\n**Memory Management**\n\n| Command | Description |\n|---|---|\n| `featherflow memory status` | Show memory snapshot and stats |\n| `featherflow memory flush` | Force-persist pending memory updates immediately |\n| `featherflow memory compact [--max-items N]` | Prune long-term snapshot to at most N items |\n| `featherflow memory list [--limit N] [--session S]` | Browse long-term snapshot entries |\n| `featherflow memory delete ` | Remove a snapshot entry by ID |\n| `featherflow memory lessons status` | Show self-improvement lesson stats |\n| `featherflow memory lessons list` | List lessons (filter by `--scope`, `--session`, `--limit`) |\n| `featherflow memory lessons enable ` | Re-enable a disabled lesson |\n| `featherflow memory lessons disable ` | Suppress a lesson from future prompts |\n| `featherflow memory lessons delete ` | Permanently remove a lesson |\n| `featherflow memory lessons compact [--max-lessons N]` | Prune lessons to at most N entries |\n| `featherflow memory lessons reset` | Wipe all lessons |\n\n**Session Management**\n\n| Command | Description |\n|---|---|\n| `featherflow session compact --session ` | Compact a single conversation session |\n| `featherflow session compact --all` | Compact all stored sessions |\n\n**Cron Scheduler**\n\n| Command | Description |\n|---|---|\n| `featherflow cron list` | List all scheduled jobs |\n| `featherflow cron add` | Add a new scheduled job |\n| `featherflow cron run ` | Trigger a job manually |\n| `featherflow cron enable ` | Enable a job |\n| `featherflow cron disable ` | Disable a job |\n| `featherflow cron remove ` | Remove a job permanently |\n\n**Configuration**\n\n| Command | Description |\n|---|---|\n| `featherflow config show` | Print all non-default config values |\n| `featherflow config provider ` | Set or update a provider's API key / base URL |\n| `featherflow config feishu` | One-shot Feishu channel + feishu-mcp setup |\n| `featherflow config pdf2zh` | Configure pdf2zh MCP server (auto-fills LLM credentials) |\n| `featherflow config mcp list` | List all configured MCP servers |\n| `featherflow config mcp add ` | Add or update an MCP server (stdio or HTTP) |\n| `featherflow config mcp remove ` | Remove an MCP server |\n\n**Providers**\n\n| Command | Description |\n|---|---|\n| `featherflow provider login openai-codex` | Authenticate with OpenAI Codex (OAuth) |\n| `featherflow provider login github-copilot` | Authenticate with GitHub Copilot (OAuth) |\n\n---\n\n## Core Capabilities\n\n### Memory & Self-Improvement\n\nFeatherFlow uses a RAM-first memory architecture:\n\n- **Session window** β unconsolidated recent context for fast recall\n- **Long-term snapshots** β periodic persistence with audit trails\n- **Lesson extraction** β automatically distills insights from user feedback and tool outcomes\n- **Configurable confidence thresholds** β controls promotion of lessons to long-term memory\n\n### Scheduled Tasks\n\nJobs can be defined as:\n\n- **Interval jobs** β run every N seconds/minutes/hours\n- **Cron expression jobs** β full cron syntax support\n- **One-time jobs** β execute at a specific datetime\n\nAll jobs can be toggled, triggered manually, or removed via the CLI.\n\n### MCP Integration\n\nConnect any MCP-compatible tool server and expose its tools directly to the agent. Define MCP servers under `tools.mcpServers` in your config. For example, connect [feishu-mcp](https://github.com/lichman0405/feishu-mcp) to bring Feishu collaboration capabilities (messages, calendar, tasks, documents) into the agent via a clean MCP interface.\n\n---\n\n## Development\n\n### Prerequisites\n\n- Python 3.11+\n- Linux or macOS (recommended)\n\n### Run Tests\n\n```bash\nPYTHONPATH=. .venv/bin/pytest -q\n```\n\n### Lint\n\n```bash\n.venv/bin/ruff check .\n```\n\n---\n\n## Migration Guide\n\nIf upgrading from a previous version or migrating from `nanobot`:\n\n| Item | Old | New |\n|---|---|---|\n| Python package | `nanobot.*` | `featherflow.*` |\n| CLI command | `assistant` | `featherflow` |\n| Runtime directory | `~/.assistant` | `~/.featherflow` |\n| Workspace directory | `~/.assistant/workspace` | `~/.featherflow/workspace` |\n\nBackward-compatible fallbacks for old config and data paths are retained where possible.\n\n---\n\n## Documentation Index\n\n### Root Documents\n\n- [README.md](README.md)\n- [CHANGELOG.md](CHANGELOG.md)\n- [CONTRIBUTING.md](CONTRIBUTING.md)\n\n### Project Docs (`docs/`)\n\n- [docs/API.md](docs/API.md)\n- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)\n- [docs/DEVELOPER_GUIDE.md](docs/DEVELOPER_GUIDE.md)\n- [docs/RAM_FIRST_MEMORY_CHECKPOINT.md](docs/RAM_FIRST_MEMORY_CHECKPOINT.md)\n- [docs/SECURITY.md](docs/SECURITY.md)\n- [docs/SELF_DEVELOPMENT.md](docs/SELF_DEVELOPMENT.md)\n\n### Skills Docs (`featherflow/skills/`)\n\n- [featherflow/skills/README.md](featherflow/skills/README.md)\n- [featherflow/skills/clawhub/SKILL.md](featherflow/skills/clawhub/SKILL.md)\n- [featherflow/skills/cron/SKILL.md](featherflow/skills/cron/SKILL.md)\n- [featherflow/skills/github/SKILL.md](featherflow/skills/github/SKILL.md)\n- [featherflow/skills/memory/SKILL.md](featherflow/skills/memory/SKILL.md)\n- [featherflow/skills/skill-creator/SKILL.md](featherflow/skills/skill-creator/SKILL.md)\n- [featherflow/skills/summarize/SKILL.md](featherflow/skills/summarize/SKILL.md)\n- [featherflow/skills/tmux/SKILL.md](featherflow/skills/tmux/SKILL.md)\n- [featherflow/skills/weather/SKILL.md](featherflow/skills/weather/SKILL.md)\n\n### Template Docs (`featherflow/templates/`)\n\n- [featherflow/templates/AGENTS.md](featherflow/templates/AGENTS.md)\n- [featherflow/templates/HEARTBEAT.md](featherflow/templates/HEARTBEAT.md)\n- [featherflow/templates/SOUL.md](featherflow/templates/SOUL.md)\n- [featherflow/templates/TOOLS.md](featherflow/templates/TOOLS.md)\n- [featherflow/templates/USER.md](featherflow/templates/USER.md)\n- [featherflow/templates/memory/MEMORY.md](featherflow/templates/memory/MEMORY.md)\n\n---\n\n## License\n\n[MIT](LICENSE)\n"}, "74a1490e1f114e74f00051d6f5b7e85dc2964b09": {"t": 1785771715.685564, "n": 13055, "h": "d5e1088c331ff5f9", "c": "# FeatherFlow\n\n\n πββ¬πͺΆ A lightweight, extensible personal AI agent framework for production automation and conversational workflows.\n
\n\n\n \n \n \n \n \n \n
\n\n---\n\n## Overview\n\nFeatherFlow is a compact AI agent runtime designed for developers who want a self-hosted, programmable assistant. It connects to any OpenAI-compatible LLM provider and exposes a rich toolset β file operations, shell execution, web search, scheduled tasks, sub-agents, and external MCP servers β all configurable via a single JSON file.\n\nFeatherFlow is a domain-focused evolution of the upstream [`nanobot`](https://github.com/HKUDS/nanobot) project. Full credit to the upstream team for the excellent engineering baseline in runtime design and tool abstraction.\n\n> **Reference baseline:** `nanobot` @ [`30361c9`](https://github.com/HKUDS/nanobot/commit/30361c9307f9014f49530d80abd5717bc97f554a) (2026-02-23)\n\n---\n\n## Features\n\n| Category | Capabilities |\n|---|---|\n| **LLM Providers** | OpenRouter, OpenAI, Anthropic, DeepSeek, Gemini, and any OpenAI-compatible endpoint |\n| **Built-in Tools** | File system, shell, web fetch/search, paper research (search/details/download), cron scheduler, sub-agent spawning |\n| **Channels** | Channel adapters exist for Feishu/Telegram/Discord/Slack/Email/QQ/DingTalk/MoChat (runtime wiring via config) |\n| **MCP Integration** | Connect any MCP-compatible tool server (e.g. [feishu-mcp](https://github.com/lichman0405/feishu-mcp)) |\n| **Memory** | RAM-first with snapshots, lesson extraction, and compact session history |\n| **Extensibility** | MCP server integration, skill files, custom provider plugins |\n| **CLI** | Interactive onboarding, agent chat, gateway mode, cron and memory management |\n\n---\n\n## Quick Start\n\n### Installation\n\n```bash\n# Clone the repository\ngit clone https://github.com/lichman0405/featherflow.git\ncd featherflow\n\n# Create and activate a virtual environment\npython3 -m venv .venv\nsource .venv/bin/activate\n\n# Install FeatherFlow\npip install --upgrade pip\npip install -e .\n\n# Verify\nfeatherflow --version\n```\n\n### First Run\n\n```bash\n# Interactive setup wizard β configures your provider, model, and identity\nfeatherflow onboard\n\n# Send a one-shot message\nfeatherflow agent -m \"hello\"\n\n# Start an interactive chat session\nfeatherflow agent\n\n# Launch the long-running gateway (channels + scheduled jobs)\nfeatherflow gateway\n```\n\n`featherflow onboard` now also supports:\n\n- Paper research tool configuration (`tools.papers` provider, API key, limits)\n\n---\n\n## Installation Options\n\n### With Dev Dependencies\n\n```bash\npip install -e '.[dev]'\n```\n\n### Docker (Recommended for Production)\n\n```bash\n# Start the gateway\ndocker compose up --build featherflow-gateway\n\n# Run a one-off CLI command in the container\ndocker compose --profile cli run --rm featherflow-cli status\n```\n\n**Runtime data directory mapping:**\n\n| Location | Path |\n|---|---|\n| Host | `~/.featherflow` |\n| Container | `/root/.featherflow` |\n\n---\n\n## Configuration\n\nFeatherFlow reads from `~/.featherflow/config.json`. The interactive wizard (`featherflow onboard`) can generate this file for you.\n\n**Default paths:**\n\n| Item | Path |\n|---|---|\n| Config file | `~/.featherflow/config.json` |\n| Workspace | `~/.featherflow/workspace` |\n\n### Configuration Skeleton\n\n```json\n{\n \"providers\": {\n \"openrouter\": {\n \"apiKey\": \"sk-or-v1-xxx\"\n }\n },\n \"agents\": {\n \"defaults\": {\n \"model\": \"anthropic/claude-opus-4-5\",\n \"name\": \"featherflow\",\n \"temperature\": 0.7\n }\n },\n \"channels\": {\n },\n \"tools\": {\n \"web\": {\n \"enabled\": true\n }\n },\n \"heartbeat\": {\n \"enabled\": true,\n \"intervalSeconds\": 1800\n }\n}\n```\n\n### Key Sections\n\n- **`providers`** β API keys and base URLs for each LLM provider.\n- **`agents.defaults`** β Default model, temperature, token limits, and agent identity.\n- **`channels`** β Channel configuration for each IM adapter (see individual channel docs).\n- **`tools`** β Web/search/fetch behavior, paper research provider settings (`tools.papers`), shell execution policy, and MCP server definitions.\n- **`heartbeat`** β Periodic background prompts (`enabled`, `intervalSeconds`) for proactive agent behaviors.\n\n> **Security:** Set file permissions to `0600` on your config file and configure strict `allowFrom` lists before exposing to any channel. See [`docs/SECURITY.md`](docs/SECURITY.md) for full guidance.\n\n---\n\n## CLI Reference\n\n**Agent & Gateway**\n\n| Command | Description |\n|---|---|\n| `featherflow onboard` | Interactive setup wizard |\n| `featherflow agent` | Start an interactive chat session |\n| `featherflow agent -m \"\"` | Send a single prompt and exit |\n| `featherflow gateway` | Run the long-running gateway (channels + cron) |\n\n**Status & Diagnostics**\n\n| Command | Description |\n|---|---|\n| `featherflow status` | Show runtime and provider status |\n| `featherflow channels status` | Show channel connection status |\n| `featherflow memory status` | Show memory snapshot and stats |\n\n**Cron Scheduler**\n\n| Command | Description |\n|---|---|\n| `featherflow cron list` | List all scheduled jobs |\n| `featherflow cron add` | Add a new scheduled job |\n| `featherflow cron run ` | Trigger a job manually |\n| `featherflow cron enable ` | Enable a job |\n| `featherflow cron disable ` | Disable a job |\n| `featherflow cron remove ` | Remove a job permanently |\n\n**Providers**\n\n| Command | Description |\n|---|---|\n| `featherflow provider login ` | Authenticate with an LLM provider |\n\n**Config (interactive wizards)**\n\n| Command | Description |\n|---|---|\n| `featherflow config show` | Print current config (keys masked) |\n| `featherflow config provider ` | Set API key / base URL for a provider |\n| `featherflow config feishu` | Configure Feishu channel **and** feishu-mcp in one step |\n| `featherflow config pdf2zh` | Configure pdf2zh MCP, auto-filling credentials from your provider |\n| `featherflow config mcp list` | List all configured MCP servers |\n| `featherflow config mcp add` | Add a custom MCP server interactively |\n| `featherflow config mcp remove ` | Remove an MCP server |\n\n---\n\n## Core Capabilities\n\n### Memory & Self-Improvement\n\nFeatherFlow uses a RAM-first memory architecture:\n\n- **Session window** β unconsolidated recent context for fast recall\n- **Long-term snapshots** β periodic persistence with audit trails\n- **Lesson extraction** β automatically distills insights from user feedback and tool outcomes\n- **Configurable confidence thresholds** β controls promotion of lessons to long-term memory\n\n### Scheduled Tasks\n\nJobs can be defined as:\n\n- **Interval jobs** β run every N seconds/minutes/hours\n- **Cron expression jobs** β full cron syntax support\n- **One-time jobs** β execute at a specific datetime\n\nAll jobs can be toggled, triggered manually, or removed via the CLI.\n\n### MCP Integration\n\nConnect any MCP-compatible tool server and expose its tools directly to the agent.\nMCP servers are defined under `tools.mcpServers` in your config β but you don't need to edit JSON by hand.\nUse the `featherflow config` commands described below.\n\n---\n\n## Chat App Setup\n\nThis guide walks through connecting FeatherFlow to a Feishu group with PDF translation.\nAll steps use the interactive `featherflow config` wizards β no JSON editing required.\n\n### Prerequisites\n\n1. **Feishu Open Platform app** β create an in-house app at , note down:\n - **App ID** β looks like `cli_xxxxxxxxxxxxxxxxxx`\n - **App Secret** β 32-character hex string\n - Grant permissions: `im:message`, `im:chat.members:read`, `drive:drive`, `docx:document`, `drive:permission:write`\n - Add bot to your target group: Group Settings β Group Bots β Add Bot\n\n2. **feishu-mcp installed** in a venv:\n ```bash\n git clone https://github.com/lichman0405/feishu-mcp ~/feishu-mcp\n cd ~/feishu-mcp && python3 -m venv .venv && .venv/bin/pip install -e .\n ```\n\n3. *(Optional)* **pdftranslate-mcp installed** in a separate Python 3.12 venv\n (required because its dependencies need Python < 3.13):\n ```bash\n git clone https://github.com/lichman0405/pdftranslate-mcp ~/pdftranslate-mcp\n cd ~/pdftranslate-mcp\n uv venv .venv --python 3.12 # or: python3.12 -m venv .venv\n .venv/bin/pip install -e .\n ```\n\n---\n\n### Step 1 β Configure Feishu channel + feishu-mcp\n\n```bash\nfeatherflow config feishu\n```\n\nWhat it asks:\n\n| Prompt | What to enter |\n|---|---|\n| `Feishu App ID` | `cli_xxxxxxxxxxxxxxxxxx` from the open platform |\n| `Feishu App Secret` | the 32-char secret (input is hidden) |\n| `Path to feishu-mcp Python executable` | auto-detected from `~/feishu-mcp/.venv/bin/python`; press Enter to accept, or paste the path manually |\n\nThis writes both `channels.feishu` and `tools.mcpServers.feishu-mcp` in one shot.\n\n---\n\n### Step 2 β Configure pdf2zh MCP (optional)\n\n```bash\nfeatherflow config pdf2zh\n```\n\nWhat it asks:\n\n| Prompt | What to enter |\n|---|---|\n| `Model name for translation` | defaults to your current model β press Enter to keep it, or type e.g. `kimi-k2.5` |\n| `Path to pdf2zh Python executable` | auto-detected from `~/pdftranslate-mcp/.venv/bin/python`; press Enter or paste path |\n\n> **Note:** API key and base URL are copied automatically from the provider you configured during `featherflow onboard`. You do **not** need to re-enter them.\n\nIf your provider base URL doesn't already end in `/v1`, the command appends it automatically.\n\n---\n\n### Step 3 β Start the gateway\n\n```bash\nfeatherflow gateway\n```\n\nFeatherFlow will connect to Feishu via WebSocket long connection and start the MCP servers as child processes. Send a message to the bot in your Feishu group to verify.\n\n---\n\n### Verify configuration\n\n```bash\nfeatherflow config show # see full config (keys masked)\nfeatherflow config mcp list # confirm feishu-mcp and pdf2zh are listed\nfeatherflow channels status # check Feishu WebSocket connection\n```\n\n---\n\n## Development\n\n### Prerequisites\n\n- Python 3.11+\n- Linux or macOS (recommended)\n\n### Run Tests\n\n```bash\nPYTHONPATH=. .venv/bin/pytest -q\n```\n\n### Lint\n\n```bash\n.venv/bin/ruff check .\n```\n\n---\n\n## Migration Guide\n\nIf upgrading from a previous version or migrating from `nanobot`:\n\n| Item | Old | New |\n|---|---|---|\n| Python package | `nanobot.*` | `featherflow.*` |\n| CLI command | `assistant` | `featherflow` |\n| Runtime directory | `~/.assistant` | `~/.featherflow` |\n| Workspace directory | `~/.assistant/workspace` | `~/.featherflow/workspace` |\n\nBackward-compatible fallbacks for old config and data paths are retained where possible.\n\n---\n\n## Documentation Index\n\n### Root Documents\n\n- [README.md](README.md)\n- [CHANGELOG.md](CHANGELOG.md)\n- [CONTRIBUTING.md](CONTRIBUTING.md)\n\n### Project Docs (`docs/`)\n\n- [docs/API.md](docs/API.md)\n- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)\n- [docs/DEVELOPER_GUIDE.md](docs/DEVELOPER_GUIDE.md)\n- [docs/RAM_FIRST_MEMORY_CHECKPOINT.md](docs/RAM_FIRST_MEMORY_CHECKPOINT.md)\n- [docs/SECURITY.md](docs/SECURITY.md)\n- [docs/SELF_DEVELOPMENT.md](docs/SELF_DEVELOPMENT.md)\n\n### Skills Docs (`featherflow/skills/`)\n\n- [featherflow/skills/README.md](featherflow/skills/README.md)\n- [featherflow/skills/clawhub/SKILL.md](featherflow/skills/clawhub/SKILL.md)\n- [featherflow/skills/cron/SKILL.md](featherflow/skills/cron/SKILL.md)\n- [featherflow/skills/github/SKILL.md](featherflow/skills/github/SKILL.md)\n- [featherflow/skills/memory/SKILL.md](featherflow/skills/memory/SKILL.md)\n- [featherflow/skills/skill-creator/SKILL.md](featherflow/skills/skill-creator/SKILL.md)\n- [featherflow/skills/summarize/SKILL.md](featherflow/skills/summarize/SKILL.md)\n- [featherflow/skills/tmux/SKILL.md](featherflow/skills/tmux/SKILL.md)\n- [featherflow/skills/weather/SKILL.md](featherflow/skills/weather/SKILL.md)\n\n### Template Docs (`featherflow/templates/`)\n\n- [featherflow/templates/AGENTS.md](featherflow/templates/AGENTS.md)\n- [featherflow/templates/HEARTBEAT.md](featherflow/templates/HEARTBEAT.md)\n- [featherflow/templates/SOUL.md](featherflow/templates/SOUL.md)\n- [featherflow/templates/TOOLS.md](featherflow/templates/TOOLS.md)\n- [featherflow/templates/USER.md](featherflow/templates/USER.md)\n- [featherflow/templates/memory/MEMORY.md](featherflow/templates/memory/MEMORY.md)\n\n---\n\n## License\n\n[MIT](LICENSE)\n"}, "aa4718f76ccae98e4b461159aafd724284901d91": {"t": 1785771717.5417442, "n": 9727, "h": "29f809a98c94c9cd", "c": "# FeatherFlow\n\n\n πββ¬πͺΆ A lightweight, extensible personal AI agent framework for production automation and conversational workflows.\n
\n\n\n \n \n \n \n \n \n
\n\n---\n\n## Overview\n\nFeatherFlow is a compact AI agent runtime designed for developers who want a self-hosted, programmable assistant. It connects to any OpenAI-compatible LLM provider and exposes a rich toolset β file operations, shell execution, web search, scheduled tasks, sub-agents, and external MCP servers β all configurable via a single JSON file.\n\nFeatherFlow is a domain-focused evolution of the upstream [`nanobot`](https://github.com/HKUDS/nanobot) project. Full credit to the upstream team for the excellent engineering baseline in runtime design and tool abstraction.\n\n> **Reference baseline:** `nanobot` @ [`30361c9`](https://github.com/HKUDS/nanobot/commit/30361c9307f9014f49530d80abd5717bc97f554a) (2026-02-23)\n\n---\n\n## Features\n\n| Category | Capabilities |\n|---|---|\n| **LLM Providers** | OpenRouter, OpenAI, Anthropic, DeepSeek, Gemini, and any OpenAI-compatible endpoint |\n| **Built-in Tools** | File system, shell, web fetch/search, paper research (search/details/download), cron scheduler, sub-agent spawning |\n| **Channels** | Channel adapters exist for Feishu/Telegram/Discord/Slack/Email/QQ/DingTalk/MoChat (runtime wiring via config) |\n| **MCP Integration** | Connect any MCP-compatible tool server (e.g. [feishu-mcp](https://github.com/lichman0405/feishu-mcp)) |\n| **Memory** | RAM-first with snapshots, lesson extraction, and compact session history |\n| **Extensibility** | MCP server integration, skill files, custom provider plugins |\n| **CLI** | Interactive onboarding, agent chat, gateway mode, cron and memory management |\n\n---\n\n## Quick Start\n\n### Installation\n\n```bash\n# Clone the repository\ngit clone https://github.com/lichman0405/featherflow.git\ncd featherflow\n\n# Create and activate a virtual environment\npython3 -m venv .venv\nsource .venv/bin/activate\n\n# Install FeatherFlow\npip install --upgrade pip\npip install -e .\n\n# Verify\nfeatherflow --version\n```\n\n### First Run\n\n```bash\n# Interactive setup wizard β configures your provider, model, and identity\nfeatherflow onboard\n\n# Send a one-shot message\nfeatherflow agent -m \"hello\"\n\n# Start an interactive chat session\nfeatherflow agent\n\n# Launch the long-running gateway (channels + scheduled jobs)\nfeatherflow gateway\n```\n\n`featherflow onboard` now also supports:\n\n- Paper research tool configuration (`tools.papers` provider, API key, limits)\n\n---\n\n## Installation Options\n\n### With Dev Dependencies\n\n```bash\npip install -e '.[dev]'\n```\n\n### Docker (Recommended for Production)\n\n```bash\n# Start the gateway\ndocker compose up --build featherflow-gateway\n\n# Run a one-off CLI command in the container\ndocker compose --profile cli run --rm featherflow-cli status\n```\n\n**Runtime data directory mapping:**\n\n| Location | Path |\n|---|---|\n| Host | `~/.featherflow` |\n| Container | `/root/.featherflow` |\n\n---\n\n## Configuration\n\nFeatherFlow reads from `~/.featherflow/config.json`. The interactive wizard (`featherflow onboard`) can generate this file for you.\n\n**Default paths:**\n\n| Item | Path |\n|---|---|\n| Config file | `~/.featherflow/config.json` |\n| Workspace | `~/.featherflow/workspace` |\n\n### Configuration Skeleton\n\n```json\n{\n \"providers\": {\n \"openrouter\": {\n \"apiKey\": \"sk-or-v1-xxx\"\n }\n },\n \"agents\": {\n \"defaults\": {\n \"model\": \"anthropic/claude-opus-4-5\",\n \"name\": \"featherflow\",\n \"temperature\": 0.7\n }\n },\n \"channels\": {\n },\n \"tools\": {\n \"web\": {\n \"enabled\": true\n }\n },\n \"heartbeat\": {\n \"enabled\": true,\n \"intervalSeconds\": 1800\n }\n}\n```\n\n### Key Sections\n\n- **`providers`** β API keys and base URLs for each LLM provider.\n- **`agents.defaults`** β Default model, temperature, token limits, and agent identity.\n- **`channels`** β Channel configuration for each IM adapter (see individual channel docs).\n- **`tools`** β Web/search/fetch behavior, paper research provider settings (`tools.papers`), shell execution policy, and MCP server definitions.\n- **`heartbeat`** β Periodic background prompts (`enabled`, `intervalSeconds`) for proactive agent behaviors.\n\n> **Security:** Set file permissions to `0600` on your config file and configure strict `allowFrom` lists before exposing to any channel. See [`docs/SECURITY.md`](docs/SECURITY.md) for full guidance.\n\n---\n\n## CLI Reference\n\n**Agent & Gateway**\n\n| Command | Description |\n|---|---|\n| `featherflow onboard` | Interactive setup wizard |\n| `featherflow agent` | Start an interactive chat session |\n| `featherflow agent -m \"\"` | Send a single prompt and exit |\n| `featherflow gateway` | Run the long-running gateway (channels + cron) |\n\n**Status & Diagnostics**\n\n| Command | Description |\n|---|---|\n| `featherflow status` | Show runtime and provider status |\n| `featherflow channels status` | Show channel connection status |\n| `featherflow memory status` | Show memory snapshot and stats |\n\n**Cron Scheduler**\n\n| Command | Description |\n|---|---|\n| `featherflow cron list` | List all scheduled jobs |\n| `featherflow cron add` | Add a new scheduled job |\n| `featherflow cron run ` | Trigger a job manually |\n| `featherflow cron enable ` | Enable a job |\n| `featherflow cron disable ` | Disable a job |\n| `featherflow cron remove ` | Remove a job permanently |\n\n**Providers**\n\n| Command | Description |\n|---|---|\n| `featherflow provider login ` | Authenticate with an LLM provider |\n\n---\n\n## Core Capabilities\n\n### Memory & Self-Improvement\n\nFeatherFlow uses a RAM-first memory architecture:\n\n- **Session window** β unconsolidated recent context for fast recall\n- **Long-term snapshots** β periodic persistence with audit trails\n- **Lesson extraction** β automatically distills insights from user feedback and tool outcomes\n- **Configurable confidence thresholds** β controls promotion of lessons to long-term memory\n\n### Scheduled Tasks\n\nJobs can be defined as:\n\n- **Interval jobs** β run every N seconds/minutes/hours\n- **Cron expression jobs** β full cron syntax support\n- **One-time jobs** β execute at a specific datetime\n\nAll jobs can be toggled, triggered manually, or removed via the CLI.\n\n### MCP Integration\n\nConnect any MCP-compatible tool server and expose its tools directly to the agent. Define MCP servers under `tools.mcpServers` in your config. For example, connect [feishu-mcp](https://github.com/lichman0405/feishu-mcp) to bring Feishu collaboration capabilities (messages, calendar, tasks, documents) into the agent via a clean MCP interface.\n\n---\n\n## Development\n\n### Prerequisites\n\n- Python 3.11+\n- Linux or macOS (recommended)\n\n### Run Tests\n\n```bash\nPYTHONPATH=. .venv/bin/pytest -q\n```\n\n### Lint\n\n```bash\n.venv/bin/ruff check .\n```\n\n---\n\n## Migration Guide\n\nIf upgrading from a previous version or migrating from `nanobot`:\n\n| Item | Old | New |\n|---|---|---|\n| Python package | `nanobot.*` | `featherflow.*` |\n| CLI command | `assistant` | `featherflow` |\n| Runtime directory | `~/.assistant` | `~/.featherflow` |\n| Workspace directory | `~/.assistant/workspace` | `~/.featherflow/workspace` |\n\nBackward-compatible fallbacks for old config and data paths are retained where possible.\n\n---\n\n## Documentation Index\n\n### Root Documents\n\n- [README.md](README.md)\n- [CHANGELOG.md](CHANGELOG.md)\n- [CONTRIBUTING.md](CONTRIBUTING.md)\n\n### Project Docs (`docs/`)\n\n- [docs/API.md](docs/API.md)\n- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)\n- [docs/DEVELOPER_GUIDE.md](docs/DEVELOPER_GUIDE.md)\n- [docs/RAM_FIRST_MEMORY_CHECKPOINT.md](docs/RAM_FIRST_MEMORY_CHECKPOINT.md)\n- [docs/SECURITY.md](docs/SECURITY.md)\n- [docs/SELF_DEVELOPMENT.md](docs/SELF_DEVELOPMENT.md)\n\n### Skills Docs (`featherflow/skills/`)\n\n- [featherflow/skills/README.md](featherflow/skills/README.md)\n- [featherflow/skills/clawhub/SKILL.md](featherflow/skills/clawhub/SKILL.md)\n- [featherflow/skills/cron/SKILL.md](featherflow/skills/cron/SKILL.md)\n- [featherflow/skills/github/SKILL.md](featherflow/skills/github/SKILL.md)\n- [featherflow/skills/memory/SKILL.md](featherflow/skills/memory/SKILL.md)\n- [featherflow/skills/skill-creator/SKILL.md](featherflow/skills/skill-creator/SKILL.md)\n- [featherflow/skills/summarize/SKILL.md](featherflow/skills/summarize/SKILL.md)\n- [featherflow/skills/tmux/SKILL.md](featherflow/skills/tmux/SKILL.md)\n- [featherflow/skills/weather/SKILL.md](featherflow/skills/weather/SKILL.md)\n\n### Template Docs (`featherflow/templates/`)\n\n- [featherflow/templates/AGENTS.md](featherflow/templates/AGENTS.md)\n- [featherflow/templates/HEARTBEAT.md](featherflow/templates/HEARTBEAT.md)\n- [featherflow/templates/SOUL.md](featherflow/templates/SOUL.md)\n- [featherflow/templates/TOOLS.md](featherflow/templates/TOOLS.md)\n- [featherflow/templates/USER.md](featherflow/templates/USER.md)\n- [featherflow/templates/memory/MEMORY.md](featherflow/templates/memory/MEMORY.md)\n\n---\n\n## License\n\n[MIT](LICENSE)\n"}, "59f6bf2da61a7b13c6b3012b51c75d1f35b214a7": {"t": 1785771719.6076615, "n": 10766, "h": "96d98d8e5af3077e", "c": "# FeatherFlow\n\n\n πββ¬πͺΆ A lightweight, extensible personal AI agent framework for production automation and conversational workflows.\n
\n\n\n \n \n \n \n \n \n
\n\n---\n\n## Overview\n\nFeatherFlow is a compact AI agent runtime designed for developers who want a self-hosted, programmable assistant. It connects to any OpenAI-compatible LLM provider and exposes a rich toolset β file operations, shell execution, web search, scheduled tasks, sub-agents, and external MCP servers β all configurable via a single JSON file.\n\nFeatherFlow is a domain-focused evolution of the upstream [`nanobot`](https://github.com/HKUDS/nanobot) project, optimized for Feishu-first production workflows. Full credit to the upstream team for the excellent engineering baseline in runtime design and tool abstraction.\n\n> **Reference baseline:** `nanobot` @ [`30361c9`](https://github.com/HKUDS/nanobot/commit/30361c9307f9014f49530d80abd5717bc97f554a) (2026-02-23)\n\n---\n\n## Features\n\n| Category | Capabilities |\n|---|---|\n| **LLM Providers** | OpenRouter, OpenAI, Anthropic, DeepSeek, Gemini, and any OpenAI-compatible endpoint |\n| **Built-in Tools** | File system, shell, web fetch/search, paper research (search/details/download), Feishu collaboration (doc/calendar/task/drive/handoff), cron scheduler, sub-agent spawning |\n| **Channels** | Feishu (WebSocket, runtime enabled) |\n| **Memory** | RAM-first with snapshots, lesson extraction, and compact session history |\n| **Extensibility** | MCP server integration, skill files, custom provider plugins |\n| **CLI** | Interactive onboarding, agent chat, gateway mode, cron and memory management |\n\n> Channel adapters for Telegram/Discord/Slack/Email/QQ/DingTalk/MoChat may exist in code, but current runtime wiring is Feishu-only.\n\n---\n\n## Quick Start\n\n### Installation\n\n```bash\n# Clone the repository\ngit clone https://github.com/lichman0405/featherflow.git\ncd featherflow\n\n# Create and activate a virtual environment\npython3 -m venv .venv\nsource .venv/bin/activate\n\n# Install FeatherFlow\npip install --upgrade pip\npip install -e .\n\n# Verify\nfeatherflow --version\n```\n\n### First Run\n\n```bash\n# Interactive setup wizard β configures your provider, model, and identity\nfeatherflow onboard\n\n# Send a one-shot message\nfeatherflow agent -m \"hello\"\n\n# Start an interactive chat session\nfeatherflow agent\n\n# Launch the long-running gateway (channels + scheduled jobs)\nfeatherflow gateway\n```\n\n`featherflow onboard` now also supports:\n\n- Paper research tool configuration (`tools.papers` provider, API key, limits)\n- Optional Feishu channel setup (can be skipped; secure defaults preserved)\n\n---\n\n## Installation Options\n\n### With Dev Dependencies\n\n```bash\npip install -e '.[dev]'\n```\n\n### Docker (Recommended for Production)\n\n```bash\n# Start the gateway\ndocker compose up --build featherflow-gateway\n\n# Run a one-off CLI command in the container\ndocker compose --profile cli run --rm featherflow-cli status\n```\n\n**Runtime data directory mapping:**\n\n| Location | Path |\n|---|---|\n| Host | `~/.featherflow` |\n| Container | `/root/.featherflow` |\n\n---\n\n## Configuration\n\nFeatherFlow reads from `~/.featherflow/config.json`. The interactive wizard (`featherflow onboard`) can generate this file for you.\n\n**Default paths:**\n\n| Item | Path |\n|---|---|\n| Config file | `~/.featherflow/config.json` |\n| Workspace | `~/.featherflow/workspace` |\n\n### Configuration Skeleton\n\n```json\n{\n \"providers\": {\n \"openrouter\": {\n \"apiKey\": \"sk-or-v1-xxx\"\n }\n },\n \"agents\": {\n \"defaults\": {\n \"model\": \"anthropic/claude-opus-4-5\",\n \"name\": \"featherflow\",\n \"temperature\": 0.7\n }\n },\n \"channels\": {\n \"feishu\": {\n \"enabled\": true,\n \"appId\": \"cli_xxx\",\n \"appSecret\": \"xxx\",\n \"allowFrom\": []\n }\n },\n \"tools\": {\n \"web\": {\n \"enabled\": true\n }\n },\n \"heartbeat\": {\n \"enabled\": true,\n \"intervalSeconds\": 1800\n }\n}\n```\n\n### Key Sections\n\n- **`providers`** β API keys and base URLs for each LLM provider.\n- **`agents.defaults`** β Default model, temperature, token limits, and agent identity.\n- **`channels`** β Feishu channel credentials and access-control settings (`allowFrom`, group read policy, reaction behavior).\n- **`tools`** β Web/search/fetch behavior, paper research provider settings (`tools.papers`), shell execution policy, and MCP server definitions.\n- **`heartbeat`** β Periodic background prompts (`enabled`, `intervalSeconds`) for proactive agent behaviors.\n\n> **Security:** Set file permissions to `0600` on your config file and configure strict `allowFrom` lists before exposing to any channel. See [`docs/SECURITY.md`](docs/SECURITY.md) for full guidance.\n\n---\n\n## CLI Reference\n\n**Agent & Gateway**\n\n| Command | Description |\n|---|---|\n| `featherflow onboard` | Interactive setup wizard |\n| `featherflow agent` | Start an interactive chat session |\n| `featherflow agent -m \"\"` | Send a single prompt and exit |\n| `featherflow gateway` | Run the long-running gateway (channels + cron) |\n\n**Status & Diagnostics**\n\n| Command | Description |\n|---|---|\n| `featherflow status` | Show runtime and provider status |\n| `featherflow channels status` | Show channel connection status |\n| `featherflow memory status` | Show memory snapshot and stats |\n\n**Cron Scheduler**\n\n| Command | Description |\n|---|---|\n| `featherflow cron list` | List all scheduled jobs |\n| `featherflow cron add` | Add a new scheduled job |\n| `featherflow cron run ` | Trigger a job manually |\n| `featherflow cron enable ` | Enable a job |\n| `featherflow cron disable ` | Disable a job |\n| `featherflow cron remove ` | Remove a job permanently |\n\n**Providers**\n\n| Command | Description |\n|---|---|\n| `featherflow provider login ` | Authenticate with an LLM provider |\n\n---\n\n## Core Capabilities\n\n### Memory & Self-Improvement\n\nFeatherFlow uses a RAM-first memory architecture:\n\n- **Session window** β unconsolidated recent context for fast recall\n- **Long-term snapshots** β periodic persistence with audit trails\n- **Lesson extraction** β automatically distills insights from user feedback and tool outcomes\n- **Configurable confidence thresholds** β controls promotion of lessons to long-term memory\n\n### Scheduled Tasks\n\nJobs can be defined as:\n\n- **Interval jobs** β run every N seconds/minutes/hours\n- **Cron expression jobs** β full cron syntax support\n- **One-time jobs** β execute at a specific datetime\n\nAll jobs can be toggled, triggered manually, or removed via the CLI.\n\n### MCP Integration\n\nConnect any MCP-compatible tool server and expose its tools directly to the agent. Define MCP servers under the `tools.mcp` section of your config.\n\n### Feishu Collaboration Workflow\n\nFeatherFlow includes a Feishu-first delivery flow for group collaboration:\n\n- `paper_download`: downloads open-access PDFs into workspace and rejects common paywall/login HTML pages with structured errors.\n- `feishu_drive`: creates Drive folders and uploads local artifacts from workspace.\n- `feishu_doc` / `feishu_task` / `feishu_calendar`: creates cloud docs, tasks, and calendar events.\n- `feishu_handoff`: generic handoff orchestration that combines uploads + optional summary doc + optional task + optional calendar event.\n\nFor group assignment (`assignees` / `attendees`), user resolution follows this order:\n- explicit `open_id`\n- current message mentions\n- group member exact name match\n- group member fuzzy name match\n\nIf multiple users match the same name, tools return candidates and fail safely instead of guessing.\n\nFeishu Open Platform permission checklist for these tools is documented in [docs/API.md](docs/API.md).\n\n---\n\n## Development\n\n### Prerequisites\n\n- Python 3.11+\n- Linux or macOS (recommended)\n\n### Run Tests\n\n```bash\nPYTHONPATH=. .venv/bin/pytest -q\n```\n\n### Lint\n\n```bash\n.venv/bin/ruff check .\n```\n\n---\n\n## Migration Guide\n\nIf upgrading from a previous version or migrating from `nanobot`:\n\n| Item | Old | New |\n|---|---|---|\n| Python package | `nanobot.*` | `featherflow.*` |\n| CLI command | `assistant` | `featherflow` |\n| Runtime directory | `~/.assistant` | `~/.featherflow` |\n| Workspace directory | `~/.assistant/workspace` | `~/.featherflow/workspace` |\n\nBackward-compatible fallbacks for old config and data paths are retained where possible.\n\n---\n\n## Documentation Index\n\n### Root Documents\n\n- [README.md](README.md)\n- [CHANGELOG.md](CHANGELOG.md)\n- [CONTRIBUTING.md](CONTRIBUTING.md)\n\n### Project Docs (`docs/`)\n\n- [docs/API.md](docs/API.md)\n- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)\n- [docs/DEVELOPER_GUIDE.md](docs/DEVELOPER_GUIDE.md)\n- [docs/RAM_FIRST_MEMORY_CHECKPOINT.md](docs/RAM_FIRST_MEMORY_CHECKPOINT.md)\n- [docs/SECURITY.md](docs/SECURITY.md)\n- [docs/SELF_DEVELOPMENT.md](docs/SELF_DEVELOPMENT.md)\n\n### Skills Docs (`featherflow/skills/`)\n\n- [featherflow/skills/README.md](featherflow/skills/README.md)\n- [featherflow/skills/clawhub/SKILL.md](featherflow/skills/clawhub/SKILL.md)\n- [featherflow/skills/cron/SKILL.md](featherflow/skills/cron/SKILL.md)\n- [featherflow/skills/github/SKILL.md](featherflow/skills/github/SKILL.md)\n- [featherflow/skills/memory/SKILL.md](featherflow/skills/memory/SKILL.md)\n- [featherflow/skills/skill-creator/SKILL.md](featherflow/skills/skill-creator/SKILL.md)\n- [featherflow/skills/summarize/SKILL.md](featherflow/skills/summarize/SKILL.md)\n- [featherflow/skills/tmux/SKILL.md](featherflow/skills/tmux/SKILL.md)\n- [featherflow/skills/weather/SKILL.md](featherflow/skills/weather/SKILL.md)\n\n### Template Docs (`featherflow/templates/`)\n\n- [featherflow/templates/AGENTS.md](featherflow/templates/AGENTS.md)\n- [featherflow/templates/HEARTBEAT.md](featherflow/templates/HEARTBEAT.md)\n- [featherflow/templates/SOUL.md](featherflow/templates/SOUL.md)\n- [featherflow/templates/TOOLS.md](featherflow/templates/TOOLS.md)\n- [featherflow/templates/USER.md](featherflow/templates/USER.md)\n- [featherflow/templates/memory/MEMORY.md](featherflow/templates/memory/MEMORY.md)\n\n---\n\n## License\n\n[MIT](LICENSE)\n"}, "f3b3dbd338bab5906f5cd6dccf5bda87a44a9f3d": {"t": 1785771720.9689004, "n": 9733, "h": "b8de97c48f42e6cf", "c": "# FeatherFlow\n\n