Installation

Engrams runs as an MCP server and requires Python 3.10+. The recommended way is uvx, which manages the Python environment automatically.

Prerequisites

  • Python 3.10+ — I recommend using pyenv
  • uv (recommended) — fast Python package manager. Install with: 
    curl -LsSf https://astral.sh/uv/install.sh | sh

Step 1 — Configure Editor

uvx runs Engrams directly from PyPI. Add the following to your MCP client's configuration file: 

{
  "mcpServers": {
    "engrams": {
      "command": "uvx",
      "args": [
        "--reinstall",
        "--from", "engrams-mcp",
        "engrams-mcp",
        "--mode", "stdio",
        "--log-level", "INFO"
      ]
    }
  }
}

Where is the config file?

ToolConfig file location
Roo Code~/.roo/mcp.json or workspace .roo/mcp.json
ClineVS Code settings → Cline → MCP Servers
Cursor~/.cursor/mcp.json
Windsurf~/.codeium/windsurf/mcp_config.json
Claude Code~/.claude/mcp.json
Claude Desktop~/Library/Application Support/Claude/claude_desktop_config.json
Workspace detection is automatic. You do not need to pass --workspace_id. Engrams detects the active project directory per-call using common project indicators (.git, package.json, etc.).

Step 2 — Install the CLI

In your project root directory, run this command to install the CLI tools:

pip install engrams-mcp

Step 3 — Initialize your project

Run engrams init from your project root. This does three things: installs the AI strategy file, sets up team or solo mode, and creates the Engrams database. 

# See all supported tools
engrams init --list

# Initialize for your AI tool (interactive — prompts for team/solo)
engrams init --tool roo
engrams init --tool cline
engrams init --tool cursor
engrams init --tool windsurf
engrams init --tool claude-code
engrams init --tool generic

# Or specify team/solo directly
engrams init --tool roo --team    # Team: decisions shared via .engrams/ + Git
engrams init --tool roo --solo    # Solo: decisions stay in local database
What does this do?
  1. Strategy file — tells your AI how and when to use Engrams tools
  2. Team/solo config — sets the default visibility for decisions
  3. Database — creates engrams/context.db with the visibility config seeded
  4. (Team only) .engrams/ directory — creates the filesystem structure for Git-shared decisions

For Roo Code users

engrams init --tool roo installs the complete Roo scaffold:

  • .roo/rules/engrams_strategy — Engrams memory strategy rules
  • .roomodes — 5 custom Flow modes (Code, Architect, Ask, Debug, Orchestrator)
  • .roo/system-prompt-flow-* — Per-mode system prompts with Engrams integration

Use --skip-prompts to install only the strategy rules without system prompt files.

Step 4 — (Team) Commit .engrams/ to Git

If you chose Team mode, Engrams created a .engrams/ directory. Commit it to share team decisions through Git: 

git add .engrams/
git commit -m "chore: initialize Engrams team sync"
git push

From this point on, every decision your AI logs with visibility=team is automatically written as a markdown file in .engrams/decisions/. When you commit and push, teammates get those decisions on their next pull.

No Git hooks required. Unlike earlier versions, v1.4 uses a write-through approach — team items are written to .engrams/ immediately when created. You just commit the directory as part of your normal Git workflow. See Team Sync for the full architecture.

Teammates joining the project

When a teammate clones the repo, they already have all team decisions in .engrams/. They just need to: 

pip install engrams-mcp
engrams init --tool roo --team   # (or their preferred AI tool)

On the first MCP tool call, Engrams auto-imports the .engrams/ files into their local SQLite cache.

Verify the installation

In a new chat, ask your AI:

What is the Engrams schema? List all available MCP tools.

If Engrams is connected, the AI will respond with a full list of tools.

No manual database setup required. The SQLite database is created automatically the first time any Engrams MCP tool is called. Do not run alembic, migration scripts, or any other database commands manually — Engrams handles this internally.

Next: Quick Start →