{"id":44219190,"url":"https://github.com/minorcell/memo-code","last_synced_at":"2026-02-18T12:07:29.775Z","repository":{"id":330755846,"uuid":"1109389220","full_name":"minorcell/memo-code","owner":"minorcell","description":"A lightweight coding agent that runs in your terminal.","archived":false,"fork":false,"pushed_at":"2026-02-10T01:28:49.000Z","size":3273,"stargazers_count":4,"open_issues_count":6,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-10T06:30:49.588Z","etag":null,"topics":["agent","code-generation","mcp","openai","skills","subagents","typescript"],"latest_commit_sha":null,"homepage":"https://memo.mcell.top/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/minorcell.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-12-03T18:28:46.000Z","updated_at":"2026-02-10T01:28:27.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/minorcell/memo-code","commit_stats":null,"previous_names":["minorcell/memo-cli","minorcell/memo-code"],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/minorcell/memo-code","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/minorcell%2Fmemo-code","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/minorcell%2Fmemo-code/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/minorcell%2Fmemo-code/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/minorcell%2Fmemo-code/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/minorcell","download_url":"https://codeload.github.com/minorcell/memo-code/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/minorcell%2Fmemo-code/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29578210,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-18T08:38:15.585Z","status":"ssl_error","status_checked_at":"2026-02-18T08:38:14.917Z","response_time":162,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent","code-generation","mcp","openai","skills","subagents","typescript"],"created_at":"2026-02-10T03:07:37.976Z","updated_at":"2026-02-18T12:07:29.770Z","avatar_url":"https://github.com/minorcell.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"public/logo.svg\" width=\"80\" height=\"80\" alt=\"Memo Logo\"\u003e\n  \u003ch1\u003eMemo Code\u003c/h1\u003e\n  \u003cp\u003eA lightweight coding agent that runs in your terminal.\u003c/p\u003e\n\u003c/div\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/minorcell/memo-code/actions/workflows/ci.yml\"\u003e\n    \u003cimg src=\"https://github.com/minorcell/memo-code/actions/workflows/ci.yml/badge.svg?branch=main\" alt=\"CI\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://codecov.io/gh/minorcell/memo-code\"\u003e\n    \u003cimg src=\"https://codecov.io/gh/minorcell/memo-code/graph/badge.svg\" alt=\"Coverage\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.com/package/@memo-code/memo\"\u003e\n    \u003cimg src=\"https://img.shields.io/npm/v/%40memo-code%2Fmemo\" alt=\"npm version\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"README.zh.md\"\u003eChinese Documentation\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cimg src=\"public/demo.png\" width=\"100%\" alt=\"Memo Code demo\"\u003e\n\nBuilt with Node.js + TypeScript. Memo works with OpenAI-compatible APIs.\n\nMemo Code is an open-source coding agent that lives in your terminal, understands repository context, and helps you move faster with natural-language commands.\n\n## Quick Start\n\n### 1. Install\n\n```bash\nnpm install -g @memo-code/memo\n# or\npnpm add -g @memo-code/memo\n# or\nyarn global add @memo-code/memo\n# or\nbun add -g @memo-code/memo\n```\n\nNote: npm distribution is prebuilt and already includes required runtime/web assets.  \n`pnpm run build` is only needed when you run Memo from source checkout in this repository.\n\n### 2. Configure API Key\n\n```bash\nexport OPENAI_API_KEY=your_key\n```\n\n### 3. Start\n\n```bash\nmemo\n# First run guides provider/model setup and saves config to ~/.memo/config.toml\n```\n\n## Usage\n\n- Interactive mode: `memo` (default TUI; supports multi-turn chat, tool visualization, shortcuts).\n- Plain mode (non-TTY): `echo \"your prompt\" | memo` (plain text output; useful for scripts).\n- One-shot mode: `memo --once \"your prompt\"` or `memo -once \"your prompt\"` (run one turn and exit; recommended with `--dangerous` in trusted repos).\n- Continue latest local session: `memo --prev` or `memo -prev` (load latest session context for current directory).\n- Dangerous mode: `memo --dangerous` or `memo -d` (skip tool approvals; use carefully).\n- Version: `memo --version` or `memo -v`.\n- Start web server: `memo web --host 127.0.0.1 --port 5494 --open` (npm package already includes web assets; source checkout needs `pnpm run build`).\n- Startup project guidance: if `AGENTS.md` exists in the startup root, Memo appends it to the system prompt automatically.\n- Skills: Memo auto-discovers `SKILL.md` files and appends an available-skills section into the system prompt.\n- MCP activation selection: when MCP servers are configured, startup shows a multi-select to activate servers for this run.\n- Web app supports multi-workspace project management and concurrent live sessions (up to 20 per server process).\n\n## Web Console\n\n```bash\nmemo web --host 127.0.0.1 --port 5494 --open\n```\n\n- npm distribution already bundles web server + web UI assets.\n- if running from source checkout, build once with `pnpm run build`.\n- Web auth config is stored in `~/.memo/server.yaml` by default (`MEMO_SERVER_CONFIG` can override path).\n- On first startup, Memo creates this file with generated auth secrets and a random password.\n- Login page uses `server.yaml` credentials (`auth.username` / `auth.password`).\n- Sidebar includes dedicated entries for `MCP Servers` and `Skills`:\n    - MCP: create/edit/remove/login/logout and active toggles.\n    - Skills: create/delete, detail preview, and active toggles.\n\n## Configuration\n\nLocation: `~/.memo/config.toml` (can be changed via `MEMO_HOME`).\n\n### Provider Configuration\n\n```toml\ncurrent_provider = \"openai_compatible\"\nauto_compact_threshold_percent = 80\n\n[[providers.openai_compatible]]\nname = \"openai_compatible\"\nenv_api_key = \"OPENAI_API_KEY\"\nmodel = \"gpt-4.1-mini\"\nbase_url = \"https://api.openai.com/v1\"\n```\n\nYou can configure multiple providers and switch with `current_provider`.\n\nOptional: override model capability profiles (local capability gating) without code changes:\n\n```toml\n[model_profiles.gpt-5]\nsupports_parallel_tool_calls = true\nsupports_reasoning_content = true\ncontext_window = 272000\n\n[model_profiles.\"openai:gpt-5\"]\nsupports_parallel_tool_calls = false # provider-specific override\n```\n\nContext window policy:\n\n- priority 1: `model_profiles.\"provider:model\".context_window`\n- priority 2: `model_profiles.\"\u003cmodel\u003e\".context_window`\n- fallback: `120000`\n\nAuto compaction policy:\n\n- threshold: `auto_compact_threshold_percent` (default `80`)\n- trigger: estimated prompt tokens at step start reaches threshold\n- frequency: at most once per turn\n\n### MCP Tool Configuration\n\nBoth local and remote MCP servers are supported:\n\n```toml\n# Local MCP server\n[mcp_servers.local_tools]\ncommand = \"/path/to/mcp-server\"\nargs = []\n\n# Remote HTTP MCP server\n[mcp_servers.remote]\ntype = \"streamable_http\"\nurl = \"https://your-mcp-server.com/mcp\"\n# headers = { Authorization = \"Bearer xxx\" }\n\n# Optional: default active MCP servers at startup\nactive_mcp_servers = [\"local_tools\", \"remote\"]\n# Optional: use [] to start with no MCP servers active\n\n# Optional: MCP OAuth credential storage mode: auto | keyring | file\nmcp_oauth_credentials_store_mode = \"auto\"\n# Optional: fixed localhost callback port for `memo mcp login`\n# mcp_oauth_callback_port = 33333\n```\n\nYou can also manage MCP configs via CLI (aligned with Codex CLI style):\n\n```bash\n# List MCP servers\nmemo mcp list\n\n# Add local MCP server (stdio)\nmemo mcp add local_tools -- /path/to/mcp-server --flag\n\n# Add remote MCP server (streamable HTTP)\nmemo mcp add remote --url https://your-mcp-server.com/mcp --bearer-token-env-var MCP_TOKEN\n\n# OAuth login/logout for streamable_http servers\nmemo mcp login remote --scopes read,write\nmemo mcp logout remote\n\n# Show/remove\nmemo mcp get remote\nmemo mcp remove remote\n```\n\n`memo mcp list` includes `auth_status` for each server: `unsupported`, `not_logged_in`, `bearer_token`, or `oauth`.\n\n## Skills\n\nMemo supports Agent Skills and auto-discovers `SKILL.md` files at startup.\n\n### Discovery Paths\n\n- Project scope: project root `.\u003cagent\u003e/skills` directories (for example: `.agents/skills`, `.claude/skills`, `.codex/skills`)\n- User scope: `$MEMO_HOME/skills` (or `~/.memo/skills`)\n- Not scanned: `~/.xxx/skills` hidden directories outside Memo home\n\n### Minimal Skill File\n\n```md\n---\nname: doc-writing\ndescription: Generate and update technical documentation.\n---\n\n# Doc Writing\n```\n\nMemo reads `name` and `description` from frontmatter and injects each skill as metadata:\n\n- `- \u003cname\u003e: \u003cdescription\u003e (file: \u003cabsolute-path-to-SKILL.md\u003e)`\n\nIn prompts, users can explicitly mention a skill with `$skill-name` (for example, `$doc-writing`).\n\nOptional: persist default active skills in `config.toml`:\n\n```toml\n# Unset: all discovered skills are active by default.\n# []: disable all skills by default.\nactive_skills = [\n  \"/absolute/path/to/.codex/skills/doc-writing/SKILL.md\"\n]\n```\n\n## Built-in Tools\n\n- `exec_command` / `write_stdin`: execute shell commands (default shell family)\n- `shell` / `shell_command`: compatibility shell variants (feature/env controlled)\n- `apply_patch`: direct string-replacement edits (single or batch)\n- `read_file` / `list_dir` / `grep_files`: file read and retrieval\n- `list_mcp_resources` / `list_mcp_resource_templates` / `read_mcp_resource`: MCP resource access\n- `update_plan`: structured task plan updates\n- `webfetch`: fetch webpages\n- `get_memory`: read memory payload from `~/.memo/Agents.md` (or `MEMO_HOME`)\n\nMore tools can be added through MCP.\n\n## Tool Approval System\n\nMemo includes a tool-approval mechanism to reduce risky operations:\n\n- **Auto-approve**: safe read tools (`read_file`, `list_dir`, `grep_files`, `webfetch`, `get_memory`, etc.)\n- **Manual approval**: risky tools (`apply_patch`, `exec_command`, etc.)\n- **Approval options**:\n    - `once`: approve this tool until current turn ends\n    - `session`: approve this tool for the current session\n    - `deny`: deny this tool until you re-approve it\n- **Approval reminders (TUI)**: when approval is required, Memo rings the terminal bell and attempts a desktop notification.\n- **Dangerous mode**: `--dangerous` skips all approvals (trusted scenarios only)\n\n## Session History\n\nAll sessions are saved to `~/.memo/sessions/`, grouped by project absolute path:\n\n```text\n~/.memo/sessions/\n  └── -Users-mcell-Desktop-workspace-memo-code/\n      ├── 2026-02-08T02-21-18-abc123.jsonl\n      └── 2026-02-08T02-42-09-def456.jsonl\n```\n\nJSONL format is useful for analysis and debugging.\n\n## Development\n\n### Run Locally\n\n```bash\npnpm install\npnpm start\n```\n\n### Build\n\n```bash\npnpm run build  # builds web-server/web-ui artifacts and generates dist/index.js\n```\n\n### Test\n\n```bash\npnpm test            # all tests\npnpm run test:coverage  # all tests with coverage (threshold: \u003e=70%)\npnpm run test:core   # core package\npnpm run test:tools  # tools package\npnpm run test:tui    # tui package\n```\n\n### Format\n\n```bash\nnpm run format        # format source/config files\nnpm run format:check  # check format (CI)\n```\n\n## Project Structure\n\n```text\nmemo-code/\n├── packages/\n│   ├── core/       # core logic: Session, tool routing, config\n│   ├── tools/      # built-in tool implementations\n│   └── tui/        # terminal runtime (CLI entry, interactive TUI, slash, MCP command)\n├── docs/           # technical docs\n└── dist/           # build output\n```\n\n## CLI Shortcuts and Commands\n\n- `/help`: show help and shortcut guide.\n- `/models`: list available Provider/Model entries and switch with Enter; also supports direct selection like `/models openai_compatible`.\n- `/review \u003cprNumber\u003e`: run GitHub PR review and publish review comments (uses active GitHub MCP server first, then falls back to `gh` CLI).\n- `/compact`: manually compact current session context.\n- `/mcp`: show configured MCP servers in current session.\n- `resume` history: type `resume` to list and load past sessions for current directory.\n- Exit and clear: `exit` / `/exit`, `Ctrl+L` for new session, `Esc Esc` to cancel current run or clear input.\n- **Tool approval**: risky operations open an approval dialog with `once`/`session`/`deny`.\n- **Approval reminder**: risky approval prompts ring a bell and attempt a desktop notification in interactive TUI.\n- **Context percent**: footer updates on each step (not just turn end), based on next-step prompt token estimate.\n\n\u003e Session logs are written only when a session contains user messages, to avoid empty files.\n\n## Tech Stack\n\n- **Runtime**: Node.js 20+\n- **Language**: TypeScript\n- **UI**: React + Ink\n- **Protocol**: MCP (Model Context Protocol)\n- **Token counting**: tiktoken\n\n## Related Docs\n\n- [User Guide (EN)](./site/content/docs/en/README.mdx) - User-facing docs by module\n- [用户指南 (ZH)](./site/content/docs/zh/README.mdx) - 中文文档入口\n- [Core Architecture](./docs/core.md) - Core implementation details\n- [CLI Adaptation History](./docs/cli-update.md) - Historical migration notes (Tool Use API)\n- [Contributing](./CONTRIBUTING.md) - Contribution guide\n- [Project Guidelines](./AGENTS.md) - Coding conventions and development process\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fminorcell%2Fmemo-code","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fminorcell%2Fmemo-code","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fminorcell%2Fmemo-code/lists"}