fubot

# Echo Agent <p align="center"> <strong>Your private Agent operating system. Multi-Agent collaboration, full-platform connection, always online.</strong> </p> <p align="center"> <a href="#quick-installation">Quick Installation</a> · <a href="#common-commands">Common Commands</a> · <a href="#gateway-api">Gateway</a> · <a href="#architecture">Architecture</a> · <a href="#development">Development</a> </p> <p align="center"> <img alt="Python 3.11+" src="https://img.shields.io/badge/python-3.11%2B-3776AB.svg?logo=python&logoColor=white&style=for-the-badge"> <img alt="Status Alpha" src="https://img.shields.io/badge/status-alpha-f59e0b.svg?style=for-the-badge"> <a href="LICENSE"><img alt="License MIT" src="https://img.shields.io/badge/license-MIT-blue.svg?style=for-the-badge"></a> <img alt="Self Hosted" src="https://img.shields.io/badge/self--hosted-111827?style=for-the-badge"> </p> **Echo Agent** is a private deployment of the Agent operating system. A team of AI consisting of planner, coder, researcher, and operator is deployed on your own server and runs 24/7. The cognitive memory system (four-layer architecture + forgetting curve + conflict detection) makes it more familiar with you; LLM-driven security approval allows high-risk operations to escape rigid rules; native A2A and MCP protocols make it a first-class citizen in the Agent Internet. From WeChat to Telegram, from CLI to Gateway API, a single entrance unifies all. Supports OpenAI, Anthropic Claude, Google Gemini, AWS Bedrock, OpenRouter, and any OpenAI-compatible endpoint. By configuring management provider, model, fallback strategy, and credential pool, the same Agent team maintains stability and controllability in different tasks and environments. <table> <tr><td><b>🧠 Cognitive Memory System</b></td><td>Four-layer memory (Working → Episodic → Semantic → Archival) + Ebbinghaus forgetting curve + conflict detection and belief versioning. BM25 + vector hybrid retrieval, the more you use, the more you understand.</td></tr> <tr><td><b>🤖 Multi-Agent Team Collaboration</b></td><td>planner, coder, researcher, knowledge, operator, and other professional Agents are automatically routed by task, supporting parallel execution, scheduling audit, and long task orchestration. One person owns an AI team.</td></tr> <tr><td><b>🔐 LLM-Driven Security Approval</b></td><td>Smart Mode uses LLM to perform real-time risk pre-examination on high-risk tool calls, goodbye to rigid black and white lists. Combined with path strategy, capability statement, and administrator approval, it is safe and flexible.</td></tr> <tr><td><b>🌐 A2A + MCP Protocol Native Support</b></td><td>Implements Google A2A (Agent-to-Agent) protocol, Agent can be discovered and called by other Agents; integrates Anthropic MCP, dynamically mounts external tools. Your Agent is a first-class node in the Internet.</td></tr> <tr><td><b>📡 Full-Platform Message Access</b></td><td>Telegram, Discord, Slack, WhatsApp, WeChat, QQ, Feishu, DingTalk, Enterprise WeChat, Matrix, Email, and 12+ channels, unified message bus, one Agent covers all platforms.</td></tr> <tr><td><b>⚡ 24/7 Resident Operation</b></td><td>CLI, message channels, Webhook, scheduled tasks, and Gateway API share the same Agent Loop. Deployed on VPS, workstation, or any infrastructure, never offline.</td></tr> <tr><td><b>🛠️ 30+ Built-in Tools + MCP Extension</b></td><td>File, Shell, Web, vision, TTS, code execution, knowledge retrieval, task orchestration, workflow engine. MCP server dynamically registers infinite extension.</td></tr> <tr><td><b>🎯 Gateway + Observability</b></td><td>REST / WebSocket API, built-in Playground, OpenTelemetry telemetry, circuit breaker, health check. Production-level infrastructure, out of the box.</td></tr> </table> --- ## Quick Installation ```bash curl -fsSL https://raw.githubusercontent.com/fuyuxiang/echo-agent/master/scripts/install.sh | bash ``` Supports Linux, macOS, and WSL2. The installation script completes Python 3.11, dependency installation, and PATH configuration; Linux environment can register systemd service for long-term operation. After installation: ```bash source ~/.bashrc # or: source ~/.zshrc echo-agent setup # interactive configuration guide echo-agent # start interactive command line ``` ### Source Code Installation ```bash git clone https://github.com/fuyuxiang/echo-agent.git cd echo-agent curl -LsSf https://astral.sh/uv/install.sh | sh uv venv venv --python 3.11 source venv/bin/activate uv pip install -e ".[all]" echo-agent setup -w . echo-agent run -w . ``` --- ## Common Commands ```bash echo-agent # start interactive command line echo-agent run # run Agent in the foreground echo-agent setup # complete configuration guide echo-agent setup model # configure model and provider echo-agent setup channel # configure message channel echo-agent status # view current configuration and running status echo-agent gateway # start Gateway service echo-agent eval -d eval.yaml # run evaluation dataset ``` ### Service Management (Linux) ```bash echo-agent service install # register systemd service echo-agent service start # start service echo-agent service stop # stop service echo-agent service status # view service status echo-agent service logs # view service logs echo-agent service restart # restart service echo-agent service uninstall # uninstall service ``` --- ## Channels All channels are normalized into unified message events and then enter the same message bus and Agent Loop. Requests from CLI, WeChat, QQBot, Telegram, and Gateway share consistent sessions, memory, tools, and permission boundaries. | Category | Channel | |------|------| | Local and System | `cli`, `webhook`, `cron` | | International Platform | `telegram`, `discord`, `slack`, `whatsapp`, `email`, `matrix` | | Domestic Ecosystem | `wechat`, `weixin`, `qqbot`, `feishu`, `dingtalk`, `wecom` | --- ## Gateway API Gateway provides HTTP / WebSocket interface for Echo Agent, suitable for accessing custom front-end, internal system, automation script, and other Agent. The root path `/` provides built-in Playground for local debugging. ```bash echo-agent gateway --host 127.0.0.1 --port 9000 ``` | Method | Path | Description | |------|------|------| | `GET` | `/` | Built-in Playground | | `GET` | `/api/v1/health` | Health Check | | `POST` | `/api/v1/message` | Send message to Agent | | `GET` | `/api/v1/sessions` | View session list | | `DELETE` | `/api/v1/sessions/{key}` | Reset Gateway session | | `POST` | `/api/v1/pair` | Generate pairing code | | `POST` | `/api/v1/pair/verify` | Verify pairing code | | `GET` | `/api/v1/stats` | Gateway running statistics | | `GET` | `/ws` | WebSocket interface | | `GET` | `/.well-known/agent.json` | A2A Agent Card | | `POST` | `/a2a` | A2A JSON-RPC entrance | Authentication supports `open`, `allowlist`, and `pairing` modes, and also supports passing API token through `X-Echo-Agent-Token` or `Authorization: Bearer`. Public deployment recommends enabling authentication and access control. --- ## Configuration Echo Agent loads configuration in the following priority: file specified by `-c` parameter > `echo-agent.yaml` in workspace > `~/.echo-agent/echo-agent.yaml`. Minimum viable configuration: ```yaml workspace: "~/.echo-agent" models: defaultModel: "gpt-4o-mini" providers: - name: "openai" apiKey: "<YOUR_API_KEY>" channels: cli: enabled: true permissions: adminUsers: - "cli_user" ``` Supported providers include `openai`, `anthropic`, `gemini`/`google`, `bedrock`/`aws`, `openrouter`, and any OpenAI-compatible endpoint. Model routing supports task type matching, fallback strategy, and credential pool rotation. Environment variable override uses `ECHO_AGENT_` prefix, and hierarchy is separated by double underscores, for example, `ECHO_AGENT_GATEWAY__PORT=9000`. --- ## Memory Echo Agent's memory system adopts a four-layer hierarchical architecture, implementing a complete life cycle management from short-term to long-term memory on top of two types of memory (user memory / environment memory). ### Memory Classification | Type | Description | |------|------| | User Memory (user) | Preferences, habits, communication style, personal context. Isolated by session, visible across sessions with `global` tag | | Environment Memory (environment) | Project facts, tool configuration, process rules, domain knowledge. Globally visible, not constrained by session isolation | ### Four-Layer Memory Hierarchy | Layer | Description | |------|------| | Working | In-memory buffer of current conversation, limited capacity (default 20 items), not persisted | | Episodic | Summary record of conversation fragments, indexed by session and time, persisted to SQLite | | Semantic | Core facts distilled from episodes, main persistence layer, supports CRUD, keyword, and vector retrieval | | Archival | Memories with importance decayed to threshold automatically archived, further decayed and then removed | ### Retrieval Hybrid retrieval pipeline (`HybridRetriever`) combines BM25 keyword matching and FAISS vector similarity, adaptively adjusting weights through query entropy (Resonance Scoring): fuzzy queries prefer vectors, precise queries prefer keywords. Retrieval results are weighted by forgetting curve and returned. Vector index is based on FAISS (optional dependency), using SQLite to persist embeddings, and automatically degraded to pure keyword retrieval when FAISS is not installed. ### Forgetting and Life Cycle Adaptive decay based on Ebbinghaus forgetting curve: `half_life = base × (1 + log₂(1 + access_count))`. The more access times, the longer half-life, and the slower forgetting. Automatically degrade to Archival layer when effective importance is below the archive threshold; thoroughly removed when below the forgetting threshold. ### Conflict Detection When new memory is written, conflict with existing memory is detected through versioned memory lattice. Supports LLM semantic verification and heuristic (different content with the same key) modes. Conflicts are not silently overwritten but stored as temporal edges, supporting belief revision and historical queries. ### Session Post-Processing After session ends, `MemoryConsolidator` writes conversation summary to `HISTORY.md` through LLM, updates long-term memory `MEMORY.md`. Complete sleep-time sorting pipeline sequentially executes: create episode → extract semantic facts and promote → conflict detection → forgetting/archive scan. ### Automatic Review `MemoryReviewer` automatically runs after non-trivial conversations, judging whether to persist user preferences, project facts, or experience lessons through LLM, and executing add / replace / remove operations. ### Security All written memory content is scanned for injection (prompt injection, role hijacking, credential leakage, etc.) and invisible Unicode character detection. File writing uses atomic replacement + cross-platform file lock to avoid data corruption caused by concurrent writing. --- ## Skills **Skills** adopt a directory + `SKILL.md` open format. Built-in skills include `arxiv`, `weather`, `summarize`, `plan`, and `skill-creator`. Skills support viewing, creating, modifying, deleting, and can be installed from local path, Git repository, or URL. --- ## Tools and Permissions 30+ built-in tools are organized by category and uniformly controlled by permission and approval system; MCP server can dynamically register external tools. | Category | Tools | |------|------| | Workspace | `read_file`, `write_file`, `edit_file`, `list_dir`, `search_files`, `patch` | | Execution | `exec`, `execute_code`, `process` | | Web | `web_fetch`, `web_search` | | Collaboration | `message`, `notify`, `clarify`, `delegate_task`, `spawn_task` | | Memory and Session | `session_search`, `memory` | | Task and Workflow | `todo`, `task`, `workflow`, `cronjob` | | Skills | `skills_list`, `skill_view`, `skill_manage`, `skill_install` | | Multimodal | `vision_analyze`, `text_to_speech`, `image_generate` | | Knowledge Base | `knowledge_search`, `knowledge_index` | | Multi-Agent | `agents_list`, `agents_route` | | MCP | Dynamically registered from configured MCP server | High-risk tools (e.g., `exec`, `write_file`, `edit_file`) default into approval process. Access control and approval strategy can be adjusted through `permissions.adminUsers` and `permissions.approval`. --- ## Architecture  ```text echo_agent/ ├── a2a/ # A2A protocol (Agent-to-Agent interoperability) ├── agent/ # Agent loop, context construction, compression, tool execution ├── bus/ # Message event queue ├── channels/ # CLI, message channels, webhook, cron adapters ├── cli/ # Configuration guide, status view, service management ├── config/ # Configuration schema, loader, default values ├── gateway/ # HTTP / WebSocket Gateway ├── knowledge/ # Knowledge base indexing and retrieval ├── mcp/ # MCP client, transport layer, OAuth ├── memory/ # Four-layer memory, hybrid retrieval, forgetting curve, conflict detection, vector index ├── models/ # Provider, routing, credential pool ├── observability/ # Health check, Span, telemetry ├── permissions/ # Permission and credential primitives ├── scheduler/ # Scheduled task service ├── security/ # Risk classification, path strategy, LLM security approval ├── session/ # Session persistence ├── skills/ # Skill storage and review ├── storage/ # SQLite backend └── tasks/ # Task management and workflow engine ``` --- ## Development ```bash git clone https://github.com/fuyuxiang/echo-agent.git cd echo-agent uv venv venv --python 3.11 source venv/bin/activate uv pip install -e ".[all,dev]" ruff check . pytest echo-agent run -w . ``` --- ## Security Recommendations - Store API key, token, and `data/credentials.json` in local environment or dedicated key management system. - Local development binds to `127.0.0.1` by default. - Enable authentication and access control before Gateway binds to `0.0.0.0`. - Shell, process, and code execution are high-privilege capabilities, recommended to be open to trusted users only. - Troubleshoot by viewing `echo-agent status`; production environment can continue to view `echo-agent service logs`. --- ## License MIT