---
name: universal-memory-setup
description: Install and configure Universal Memory for local CLI and MCP stdio clients. Use when an agent needs portable project context or shared local memory.
---

# Universal Memory Setup

Universal Memory is a local-first persistence layer for AI agents. Use these steps to install it, initialize a workspace, and connect its local MCP server.

## Requirements

- Python 3.12 or newer.
- `uv` for the recommended install and one-off commands.
- A local project directory where the user has authorized initialization.

## Guardrails

- Treat Universal Memory as a local tool; this skill does not advertise a hosted MCP endpoint.
- Do not store secrets, tokens, raw environment dumps, or private data as memory.
- Ask before initializing a repository or mutating durable project memory.
- Prefer explicit `remember`, purge, and sync operations that remain auditable.

## Try without installing

```bash
uvx --from universal-memory umem --help
uvx --from universal-memory umem status
```

## Persistent installation

```bash
uv tool install universal-memory
umem init --runtime codex
umem status
```

Choose only runtimes the user actually uses. Other supported runtime identifiers are documented at <https://docs.universal-memory.com/>.

## Local MCP server

For a one-off MCP launch:

```bash
uvx --from universal-memory umem-mcp
```

Example client configuration:

```json
{
  "mcpServers": {
    "universal-memory": {
      "command": "uvx",
      "args": ["--from", "universal-memory", "umem-mcp"]
    }
  }
}
```

After a persistent installation, clients may use `umem-mcp` as the command with no arguments.

## Verify

```bash
umem status --format json
umem context --scope project --format json
umem skills list --format json
```