Memo Code

A lightweight coding agent that runs in your terminal.

Chinese Documentation

---

Built with Node.js + TypeScript. DeepSeek is the default provider, and OpenAI-compatible APIs are supported.

Memo Code is an open-source coding agent that lives in your terminal, understands repository context, and helps you move faster with natural-language commands.

Quick Start

1. Install

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

2. Configure API Key

export DEEPSEEK_API_KEY=your_key  # or OPENAI_API_KEY

3. Start

memo
# First run guides provider/model setup and saves config to ~/.memo/config.toml

Usage

• Interactive mode: memo (default TUI; supports multi-turn chat, streaming, tool visualization, shortcuts).
• One-shot mode: memo "your prompt" --once (plain text output; useful for scripts).
• Dangerous mode: memo --dangerous or memo -d (skip tool approvals; use carefully).
• Version: memo --version or memo -v.

Configuration

Location: ~/.memo/config.toml (can be changed via MEMO_HOME).

Provider Configuration

current_provider = "deepseek"
stream_output = false

[[providers.deepseek]]
name = "deepseek"
env_api_key = "DEEPSEEK_API_KEY"
model = "deepseek-chat"
base_url = "https://api.deepseek.com"

You can configure multiple providers and switch with current_provider.

MCP Tool Configuration

Both local and remote MCP servers are supported:

# Local MCP server
[mcp_servers.local_tools]
command = "/path/to/mcp-server"
args = []

# Remote HTTP MCP server
[mcp_servers.remote]
type = "streamable_http"
url = "https://your-mcp-server.com/mcp"
# headers = { Authorization = "Bearer xxx" }

You can also manage MCP configs via CLI (aligned with Codex CLI style):

# List MCP servers
memo mcp list

# Add local MCP server (stdio)
memo mcp add local_tools -- /path/to/mcp-server --flag

# Add remote MCP server (streamable HTTP)
memo mcp add remote --url https://your-mcp-server.com/mcp --bearer-token-env-var MCP_TOKEN

# Show/remove
memo mcp get remote
memo mcp remove remote

Built-in Tools

• bash: execute shell commands
• read: read files
• write: write files
• edit: edit files
• glob: find files by pattern
• grep: search content by regex
• webfetch: fetch webpages
• save_memory: save long-term memory
• todo: manage a task list

More tools can be added through MCP.

Tool Approval System

Memo includes a tool-approval mechanism to reduce risky operations:

• Auto-approve: safe tools (read, glob, grep, etc.)
• Manual approval: risky tools (bash, write, edit, etc.)
• Approval options:
  • once: approve current operation only
  • session: approve all matching operations for this session
  • deny: reject operation
• Dangerous mode: --dangerous skips all approvals (trusted scenarios only)

Session History

All sessions are saved to ~/.memo/sessions/, grouped by working directory and date:

~/.memo/sessions/
  ├── workspace-name/
  │   ├── 2026-02-01_143020_abc123.jsonl
  │   └── 2026-02-01_150315_def456.jsonl
  └── another-project/
      └── 2026-02-01_160000_xyz789.jsonl

JSONL format is useful for analysis and debugging.

Development

Run Locally

pnpm install
pnpm start
# or
pnpm start "prompt" --once

Build

pnpm run build  # generates dist/index.js

Test

pnpm test                   # all tests
pnpm test packages/core     # core package
pnpm test packages/tools    # tools package

Format

npm run format        # format all files
npm run format:check  # check format (CI)

Project Structure

memo-cli/
├── packages/
│   ├── core/       # core logic: Session, tool routing, config
│   ├── tools/      # built-in tool implementations
│   └── cli/        # TUI interface
├── docs/           # technical docs
└── dist/           # build output

CLI Shortcuts and Commands

• /help: show help and shortcut guide.
• /models: list available Provider/Model entries and switch with Enter; also supports direct selection like /models deepseek.
• /context: open 80k/120k/150k/200k options and apply immediately.
• $ <cmd>: run a local shell command in current cwd and display result directly (Shell Result).
• resume history: type resume to list and load past sessions for current directory.
• Exit and clear: exit / /exit, Ctrl+L for new session, Esc Esc to cancel current run or clear input.
• Tool approval: risky operations open an approval dialog with once/session/deny.

Session logs are written only when a session contains user messages, to avoid empty files.

Tech Stack

• Runtime: Node.js 18+
• Language: TypeScript
• UI: React + Ink
• Protocol: MCP (Model Context Protocol)
• Token counting: tiktoken

Related Docs

• User Guide - User-facing docs by module
• Core Architecture - Core implementation details
• CLI Adaptation History - Historical migration notes (Tool Use API)
• Contributing - Contribution guide
• Project Guidelines - Coding conventions and development process

License

MIT