Echo Agent: a self-hosted agent runtime that keeps its memory

The problem Echo Agent targets: an agent that forgets everything between runs

Most agent frameworks treat a conversation as the unit of work. You start a session, the model reasons over a context window, and when the process exits the state goes with it. That is fine for a coding assistant you invoke per task. It breaks down when you want something that runs continuously on a server, receives messages from several places, and is expected to remember what it learned last week.

Echo Agent is aimed at that second case. The README describes it as a self-hosted, long-running agent, and the feature list is organised around the consequences of running for months rather than minutes: memory that decays instead of growing without bound, contradiction detection when new facts disagree with old ones, skills that are regenerated from real execution traces and can be rolled back, and a single approval path for high-risk tool calls. The intended user is an individual or a small team with a server, at least one model API key, and a preference for keeping conversation data on their own disk. The default data directory is ~/.echo-agent.

Four memory layers, hybrid retrieval, and the agent loop underneath

The memory system is split into four named layers: Working, Episodic, Semantic and Archival. The README pairs them with decay, contradiction detection and importance-based re-ranking, and states that the point is to solve memory bloat under long-running operation. That is a real problem: an append-only store of every exchange becomes useless as a retrieval target within weeks, because everything is roughly equally similar to everything else. Decay plus re-ranking is a plausible answer, though the README does not publish the decay function or the thresholds, so you cannot predict from the docs how quickly a given fact fades.

Retrieval is hybrid: BM25 plus FAISS vector search, fused with weights adapted to the query, and the docs say it degrades automatically when FAISS is unavailable. That fallback matters on machines where the embedding stack will not build, because it means the knowledge base still returns lexical matches rather than failing outright. Embeddings come from fastembed, which is a declared dependency.

The execution path is described as one loop shared across every entry point: an event arrives, context is assembled, a model is called, tools run, and the result is recorded. Because channels share the loop and the state, a message that arrives over Telegram and a command typed into the CLI act on the same memory. The README notes that CLI sessions are independent but memory is shared.

Two architectural details are worth flagging. First, model routing is configurable per role: main reasoning, context compression, embeddings and risk approval can each point at a different provider. Second, cross-process interoperability is asymmetric. Echo Agent implements an A2A JSON-RPC inbound endpoint and an MCP client with OAuth and dynamic tool registration, but the README states plainly that the agent runtime does not currently provide an A2A outbound delegation entry point. It can be called as an agent; it cannot delegate to another agent over that protocol.

Installing Echo Agent and getting a first conversation

Echo Agent requires Python 3.11 or newer and at least one model API key. The README gives a three-command path. The first installs from PyPI with the all extras group, which pulls in the full dependency set including the TUI and embedding packages.

pip install "echo-agent[all]"

The second command runs an interactive setup wizard. It walks through entering a model API key and writes configuration under ~/.echo-agent by default. The third starts an interactive conversation in the terminal, reading input line by line.

echo-agent setup
echo-agent run

If you are on a network where PyPI is slow, the README suggests an Aliyun mirror by appending -i https://mirrors.aliyun.com/pypi/simple/ to the install command. On Windows the same three commands work in PowerShell.

There is a second, separate installation path for source checkouts. The scripts/install.sh script clones the repository into ~/.echo-agent, creates its own virtual environment, installs the all extras, and can register the gateway as a persistent service. The README recommends downloading it first and reading it before running, which is sensible for a script that installs a background service.

curl -fsSL -o install.sh https://raw.githubusercontent.com/fuyuxiang/echo-agent/master/scripts/install.sh
less install.sh && bash install.sh

The script accepts --repo gitee or --repo github to pin the clone source, --reconfigure to re-run the wizard, and --skip-setup to install code only. One caveat the README calls out: --repo only affects git clone and fetch. The embedding and reranking model bundles are hosted in split volumes and always download Gitee-first with a GitHub fallback, regardless of that flag. Re-running the script is the upgrade path; if a working configuration is detected, the wizard is skipped and existing settings are preserved.

For a long-running deployment, echo-agent run and echo-agent gateway are both foreground processes that die with the terminal. The documented way to keep the agent alive is to register the gateway as a user-level service, which on macOS means a LaunchAgent and on Linux a user systemd unit, neither requiring root.

echo-agent gateway install
echo-agent gateway start
echo-agent gateway status
echo-agent gateway logs -f

Once the gateway is up, echo-agent cli attaches to the same resident agent from any terminal on the machine. The gateway listens only on 127.0.0.1 loopback and the README says remote addresses are not supported; remote access is expected to go over ssh. Two environment differences are documented: on Linux the user service stops when the login session ends unless you run sudo loginctl enable-linger $USER, and on systems without systemd, including default WSL2 and containers, the README suggests holding the foreground process in tmux instead.

The approval gate, and why unattended channels refuse instead of asking

The safety model is the part of Echo Agent with the clearest design stance. High-risk tool calls, which the README lists as command execution and file operations, go through a unified approval step with three policies: manual, smart and off. Credentials are stored encrypted and execution logs are auditable.

The interesting detail is the default for unattended channels. When a high-risk call arrives over a channel where no human is present to answer, the documented behaviour is to refuse rather than proceed. That is the right default for a system that can run shell commands on your server, and it also means an agent driven only by a Telegram bot will decline work that a CLI session would let through after a prompt. If your use case is unattended automation of file or command operations, you will be configuring this deliberately rather than relying on defaults.

The smart policy implies an LLM judges calls rather than a static allowlist, and the README lists risk approval as one of the roles you can point at a separate model provider. That is a reasonable separation: a cheap model can screen calls before the main reasoning model ever sees them. It also introduces a dependency the README does not quantify. If the approval model is unreachable, the documented default posture points toward refusal, but the docs do not state a timeout or a fallback behaviour for that specific failure. That is worth testing before you wire the agent to anything that matters.

The gateway has a second boundary worth understanding. A zero-configuration loopback gateway accepts only two kinds of client: echo-agent cli, and native clients such as scripts or SDKs that do not send a browser Origin header. Browser requests carrying a cross-site Origin are rejected outright, which the README frames as CSRF protection against a web page driving the local agent through the user's browser. Opening browser or playground access requires changing the gateway authentication configuration, and the README links to a dedicated page for that rather than describing it inline.

Where Echo Agent is the wrong choice

The project classifies itself as Development Status 4 - Beta in pyproject.toml. Treat that as the operative constraint. The CLI, the configuration keys and the gateway API can change between minor releases, and the release cadence supports that reading: three releases between 2026-07-22 and 2026-08-18. The last push to the repository was on 2026-08-18. If you need a frozen integration surface, this is not it yet.

The single-machine assumption is the second limit. The gateway binds to loopback and the README says remote addresses are unsupported, directing remote users to ssh. That rules out the common deployment where the agent runs in a cluster and clients connect over a network. It is a deliberate security trade-off, and it means scaling out is not a configuration change.

The third limit is protocol coverage. Because the runtime has no A2A outbound delegation, Echo Agent cannot be the orchestrator in a multi-agent A2A topology. It can accept inbound tasks and it can consume MCP servers, but it cannot hand work to a peer agent over A2A. If your architecture assumes agents calling agents, this is the wrong layer.

Finally, the memory quality claims are the hardest to evaluate from the repository alone. Decay curves, contradiction detection and importance re-ranking are all described in the README as features, but the docs do not publish the parameters, and there is no benchmark in the repository. You are trusting a design, not a measured result. Anyone whose workflow depends on precise recall of old facts should test that directly before committing.

How Echo Agent differs from OpenHands-style agent sandboxes

The closest comparison point in this space is OpenHands, which puts the agent in a containerised sandbox and frames the task as software engineering: the agent edits a repository, runs tests, and the sandbox is the security boundary. Isolation is the mechanism, and the unit of work is a task that ends.

Echo Agent inverts both choices. There is no sandbox in the described architecture. The agent runs directly on the host, and the security boundary is procedural instead: an approval gate in front of high-risk tools, encrypted credentials, and an audit log. That is a weaker boundary than a container in the general case, and it is a deliberate trade in exchange for the agent being able to touch the real filesystem, the real cron scheduler and the real messaging channels. You cannot have a Telegram bot that manages your actual machine if the bot lives in a disposable container.

The second difference is the unit of work. OpenHands-style sessions terminate; Echo Agent is built to persist, with memory layers that decay and skills that are regenerated and rolled back. The skill evolution mechanism is the more unusual half: the README describes recording execution traces, generating candidate improvements, validating them against an evaluation before promotion, and supporting a cooldown period and one-click rollback. That is a software change pipeline applied to agent behaviour, and it is a meaningfully different bet from shipping a fixed tool set.

If your problem is "fix this issue in this repo", the sandbox model is better matched. If your problem is "run continuously on my server and remember what happened", the persistent-runtime model is the one you want, and you accept that the safety story rests on policy rather than isolation.

Editorial conclusion

Echo Agent fits people who want an agent on their own hardware with memory that survives restarts and an approval gate in front of shell and file operations. Skip it if you want a managed service, a stable API, or an agent that can call out to other agents over A2A, since only the inbound side exists. Before adopting, run echo-agent status after setup to confirm which model provider and channels are actually active, and read the tool approval policy section of the docs, because the default behaviour on unattended channels is to refuse high-risk calls rather than ask.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes