metis

Metis is an MCP server that powers persistent memory and memory-driven project management for AI coding agents. It exposes a structured workflow with Vision, Initiative, and Task documents, stored in markdown with YAML frontmatter inside a .metis/ workspace. You interact with Metis through the provided MCP tools to initialize a workspace, create and read documents, transition phases, and search or index code. Use Claude integration to automatically detect projects, generate visions, and break work into initiatives and tasks, while preserving progress across sessions and context windows.

Prerequisites:

• Node.js and npm (recommended latest LTS)
• curl (for the official install script)

Installation steps:

1. Run the official installer to install the Metis desktop app and CLI (which includes the MCP server):

   curl -fsSL https://raw.githubusercontent.com/colliery-io/metis/main/scripts/install.sh | bash

2. Launch Metis once to ensure the CLI is added to your PATH. The first launch installs the metis CLI (and MCP server) system-wide.

3. (Optional) Manual install methods:

   • macOS (Apple Silicon): Metis_x.x.x_aarch64.dmg
   • macOS (Intel): Metis_x.x.x_x64.dmg
   • Windows: Metis_x.x.x_x64-setup.exe
   • Linux: Metis_x.x.x_amd64.AppImage

4. Verify installation by running Metis commands (via the CLI):

   metis --version claude mcp add --scope user --transport stdio metis -- metis mcp

5. Start the MCP server through the chosen launcher (e.g., the Node-based npx option will fetch and start the server when invoked as configured). Ensure the server is reachable by your MCP client tooling.

Tips and caveats:

• The Metis workflow relies on a .metis/ directory in your project. Documents and versions live there and survive context changes, compaction, or session restarts.
• If you run into quarantine warnings on macOS after installing via a package, you may need to run: sudo xattr -rd com.apple.quarantine "/Applications/Metis.app".
• The MCP integration expects you to initialize a workspace and then add documents (Vision, Initiative, Task, ADR, Specification) using the MCP tools.
• For autonomous task execution (Metis Ralph), use the /metis-ralph SHORT_CODE command to trigger loops, and /cancel-metis-ralph to stop.
• When configuring paths or environment, you can set METIS_CLI_PATH or METIS_CONFIG as placeholders for custom setups; adjust as needed for your environment.