Free · Open source · Apache-2.0
Keep your agent’s history on disk, not in the prompt.
ECHO.md is a small change journal for local AI agents. echoctl saves your agent files as numbered, SHA-256-checked versions in a .echo/ folder, and keeps a short ECHO.md summary (4 KB by default) your agent can read instead of its whole history.
- No account, no network calls, no telemetry
- Python and TypeScript versions that read and write the same history
- Restore any version into an empty folder, then check every byte written
- Skips .env files, keys, symlinks and files that look like they hold secrets
- Free to use, change and enter in hackathons and contests
Install
Clone the GitHub repository or unzip the download, then pick a version. Neither needs extra packages.
Python 3.11+
pip install ./echo-md/python
cd ~/my-agent
echoctl initNode 22.18+
cd ~/my-agent
node ~/echo-md/typescript/src/cli.ts initCommands
echoctl init --adapter generic # or --adapter hermes
echoctl status
echoctl capture -m "before prompt rewrite"
echoctl history --limit 10
echoctl diff v3 v4 --path AGENTS.md
echoctl verify v4
echoctl restore v3 --to ./restored
echoctl receipt v4 > receipt.jsonAdd --json to any command for output a script or agent can read.
What it doesn’t do
- It can’t recover history from before you run init
- It saves a version when you run capture; edits in between aren’t recorded one by one
- A matching hash proves the files are identical, not that the agent behaves the same
- Secret detection is a pattern check and can miss things
Tested
Both versions are checked against each other: each reads, verifies and restores the other’s history, spots tampered files, skips secrets and symlinks, and keeps ECHO.md within its size limit across 120 versions.
When you need more than your own laptop
echoctl receipt fingerprints a version the same way Echo Vault does, so the same files give the same fingerprint in both. Echo Vault adds private hosted history, change reviews, staging and production labels, GitHub tracking and continuity reports.