Getting started

Getting started

From a fresh clone to a session that reads its memory, in five steps. Takes about ten minutes.

Tip

Installing with an agent? Point it at .agents/install.md. It covers the same steps, plus the checks an agent should run before calling the install done.

What you need

	version	check with
Python	3.12 or newer	python --version
Node	22.18 or newer, optional (builds the dashboard; without it the install takes the release's prebuilt one)	node --version
git	any	git --version

---

1. Clone and install

git clone <repository-url> MemAI
cd MemAI

On Windows, run install.bat. It creates .venv, installs MemAI and its locked dependencies into it, and builds the dashboard, or downloads the release's prebuilt one when Node or the npm registry is out of reach.

Elsewhere:

python -m venv .venv
.venv/bin/pip install --no-deps -e .
.venv/bin/pip install --require-hashes -r requirements-dev.txt
.venv/bin/python tools/install-webui.py

The lock files pin every dependency with a hash, so the install reproduces the set the tests ran against. install-webui.py builds the dashboard with Node, or fetches the release's prebuilt one and checks it against its .sha256. A machine with no internet takes the zip by hand: install.bat --webui-zip <path> (elsewhere install-webui.py --zip <path>).

The checkout is the install (pip install -e): editing or pulling the source changes what the next server runs. Do not install MemAI a second time into your system Python.

2. Check the install

.venv/Scripts/python -m pytest -q      # .venv/bin/python off Windows

The suite is self-contained. If it fails, fix that before going further: it is an install problem, not a configuration one.

3. Register the MCP server

Name the server memai and give the absolute path to the launcher in the venv.

claude mcp add --scope user memai "C:\path\to\MemAI\.venv\Scripts\memai-mcp.exe"

That writes the entry for the Claude Code CLI. The Claude desktop app reads a different file, so register it there too if you use it:

host	the file it reads
Claude Code CLI (claude in a terminal)	~/.claude.json
Claude desktop app — Chat and the Code tab	Windows: %APPDATA%\Claude\claude_desktop_config.json macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "memai": {
      "command": "C:\\path\\to\\MemAI\\.venv\\Scripts\\memai-mcp.exe"
    }
  }
}

Important

Use the absolute path. A desktop app inherits the desktop session's PATH, not your shell's, so a bare memai-mcp usually does not resolve. And keep the name memai: tool names are built from it (mcp__memai__search), and the bundled warden subagent matches those names exactly.

Restart the host after editing its file — it reads the config once, at startup.

4. Install the hooks, skills and warden

memai-hook install            # the four hook events
memai-hook install --skills   # the bundled skills
memai-hook install --agents   # the warden subagent
memai-hook install --check    # confirm: everything registered, nothing outdated

memai-hook lives in the venv (.venv\Scripts\ on Windows, .venv/bin/ elsewhere). Run it from there, or with the venv activated. These write into ~/.claude (settings.json, skills/, agents/), back up whatever they replace, and cover every project at once. Without the hooks, a session only reads its memory when it remembers to — see How a session uses memory.

5. Open a session

Start a new Claude Code session in any project. You should see:

1. MemAI: brief loaded (…) — the session-start hook put the store's state in the session's context.
2. The agent calls pulse() or must_read() before anything else. Until it does, its other tools are held.
3. MemAI: session warmed up with pulse(…) — it has read its memory and works normally from here.

On an empty store the brief is short; it fills as the agent writes. Open the dashboard to watch it happen:

memai-admin          # http://127.0.0.1:8888

On Windows, run-admin.bat does the same.

---

Next: Memory types — what the agent writes, and when.