Memo started with a simple question: What does the simplest Agent look like?
In the second half of 2024, while writing my tech blog post Agent = LLM + TOOL, I began thinking about the essence of Agents — nothing more than LLM + Tool loops. But when I actually started implementing it, I discovered that behind every seemingly simple feature lies a mountain of engineering details:
- Best practices for system prompts
- Tool design and security boundaries
- Multi-model switching and compatibility
- Context management (especially long-session compaction strategies)
- Tricky TUI interactions
- Multi-workspace support
- npm package distribution and hot-reloading
- ...
This project grew from a small demo into an indispensable "productivity assistant" in my daily development — it helps me update documentation, manage GitHub Issues, debug projects... While I still use Claude Code and Codex CLI as my primary development tools, Memo quietly handles the tedious tasks in the background.
This is a personal project built from scratch. All architectural designs and technical decisions are independent explorations and trade-offs. If you're interested in the engineering implementation of Agents, I hope Memo can give you some reference.
| Feature | Description |
|---|---|
| Terminal Mode | Smooth TUI in terminal |
| Smart Context Management | Auto-compact long session context, configurable threshold, millisecond-level token estimation |
| Skills System | Skills integration, auto-discover SKILL.md, activate by scenario |
| Deep MCP Integration | Local/remote MCP servers, OAuth login, per-session dynamic switching |
| Enterprise-Grade Security | Tool approval system (auto-approve/manual-approve), supports once/session/deny modes |
| OpenAI Compatible | Works with any OpenAI-compatible API, flexible multi-Provider configuration |
npm install -g @memo-code/memo
# or pnpm / yarn / bunexport OPENAI_API_KEY=your_key
# or configure other compatible APIsmemoFirst run will guide you through Provider/Model setup and save config to ~/.memo/config.toml.
| Mode | Command | Scenario |
|---|---|---|
| Interactive | memo |
Default, full TUI experience |
| One-shot | memo --once "prompt" |
Run once and exit |
| Resume Session | memo --prev |
Load latest session for current directory |
memo-code/
├── packages/
│ ├── core/ # Agent engine: session state machine, LLM/tool loop, built-in tools, MCP client, skills
│ └── tui/ # Terminal runtime: CLI entry, interactive TUI (Ink)
└── site/ # Documentation website (Next.js, static export)
Technical Highlights:
- Architecture: Core engine with integrated tool routing, thin TUI on top, state-machine driven session management
- Testing: Unit + integration tests, coverage threshold ≥70%
- Protocol: Native MCP (Model Context Protocol) support, can integrate any MCP tool server
- Token Estimation: Real-time context monitoring based on tiktoken, configurable auto-compaction strategy
- Distribution: Published to npm with version-driven auto releases via CI
exec_command/write_stdin- Execute Shell commandsapply_patch- Structured patch editing (*** Begin Patch/*** End Patch)read_text_file/read_media_file/read_files/write_file/edit_file/list_directory/search_files- Filesystem read/write/searchwebfetch- Paged web fetching with markdown extraction and policy guards- MCP resource access -
list_mcp_resources,list_mcp_resource_templates,read_mcp_resource update_plan- Structured task progress managementread_skill- Load skill instructions on demandget_memory- Persistent memory reading- Agent collaboration -
spawn_agent/send_message/followup_task/wait_agent/interrupt_agent/list_agents
current_provider = "openai_compatible"
auto_compact_threshold_percent = 80
[[providers.openai_compatible]]
name = "openai_compatible"
env_api_key = "OPENAI_API_KEY"
model = "gpt-4.1-mini"
base_url = "https://api.openai.com/v1"
# MCP Server
[mcp_servers.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
# Skills (absolute paths to SKILL.md files)
active_skills = ["/path/to/skills/doc-writing/SKILL.md"]# Install dependencies
pnpm install
# Run locally
pnpm start
# Build for distribution
pnpm run build
# Test
pnpm test # all tests
pnpm run test:coverage # coverage report (threshold ≥70%)
# Format
pnpm run format # write
pnpm run format:check # CI checkMIT License