memo-code

Memo Code A lightweight coding agent for terminal workflows.

Website
·
Documentation
·
中文文档



  


  


  

---

🌱 Origin

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.

---

✨ Features

Feature	Description
Terminal TUI	Interactive terminal UI with streaming markdown, thinking previews, and live plan progress
Smart Context Management	Auto-compact long session context, configurable threshold, byte-based token estimation
Session Resume	Resume past sessions with model, thinking mode, and UI state restored
Skills System	Auto-discover SKILL.md across project and user roots, dedup, built-in skill-creator
Multi-Agent Collaboration	Parallel subagents with independent context, split large tasks and collect results
Deep MCP Integration	Local/remote MCP servers, OAuth login, per-session dynamic switching
Built-in Tools	File I/O and search, command execution, structured patching, web fetch, MCP resource browsing
Memory System	Persistent memory read, keeps preferences and project context across sessions
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

---

🚀 Quick Start

1. Install

npm install -g @memo-code/memo
# or pnpm / yarn / bun

2. Configure API Key

export OPENAI_API_KEY=your_key
# or configure other compatible APIs

3. Run

memo

First run will guide you through Provider/Model setup and save config to ~/.memo/config.toml.

---

📖 Usage Modes

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

CLI Subcommands

memo init               # generate AGENTS.md for the current project
memo mcp list|add|login # manage MCP servers
memo skills list|read   # discover and read skills

---

🏗️ Architecture

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 with byte-based estimation, configurable auto-compaction strategy
• Distribution: Published to npm with version-driven auto releases via CI

---

🔧 Built-in Tools

• exec_command / write_stdin - Execute Shell commands
• apply_patch - Structured patch editing (*** Begin Patch/*** End Patch)
• read / write_file / edit_file / list_directory / search_files - Filesystem read/write/search
• webfetch - 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 management
• read_skill - Load skill instructions on demand
• get_memory - Persistent memory reading
• Agent collaboration - spawn_agent / send_message / followup_task / wait_agent / interrupt_agent / list_agents

---

⚙️ Config Example

current_provider = "openai_compatible"
auto_compact_threshold_percent = 80

[[providers.ope