Getting Started

This guide walks you through installing mememory, starting the infrastructure, and connecting your first MCP client.

Prerequisites

• PostgreSQL >= 14 with the pgvector extension (BYO or bundled)
• Docker and Docker Compose (only if you want the bundled quick-start stack)
• A supported MCP client (Claude Code, Claude Desktop, or any MCP-compatible agent)

Installation

Bundled Docker stack (recommended quick-start)

The Docker stack includes everything: PostgreSQL with pgvector, Ollama for embeddings, the admin API, and the MCP server.

go install github.com/scott-walker/mememory/cmd/mememory@latest
mememory setup

mememory setup extracts the bundled Docker Compose file, resolves a data directory, and runs docker compose up -d. No source checkout required. To stop the stack later use mememory uninstall (data preserved).

Bring your own Postgres

DATABASE_URL is required — there is no fallback. Set it to a PostgreSQL >= 14 instance with pgvector available:

export DATABASE_URL=postgres://user:pass@your-host:5432/mememory?sslmode=disable
mememory-server

The server runs CREATE EXTENSION IF NOT EXISTS vector at startup. If your DB user lacks CREATE privilege, ask your DBA to install pgvector beforehand.

The MCP server runs inside the mememory container. Your MCP client connects to it via docker exec.

Go Install (native binary)

If you want the mememory CLI on your host for bootstrap and status commands:

go install github.com/scott-walker/mememory/cmd/mememory@latest

This installs the mememory binary to your $GOPATH/bin. You still need Docker for PostgreSQL and Ollama.

Pre-built binaries

Download from GitHub Releases — linux_amd64, linux_arm64, darwin_amd64, darwin_arm64, and windows_amd64 are published for every tag.

First-Time Setup

1. Start infrastructure

mememory setup

This starts three containers:

Container	Port	Purpose
mememory-postgres	5432	PostgreSQL with pgvector extension
mememory-ollama	11434	Ollama embedding server (nomic-embed-text)
mememory	4200	Admin API + web UI + MCP server

TIP

On first start, Ollama downloads the nomic-embed-text model (~275 MB). This happens automatically inside the Docker container.

2. Verify services are running

# Check all containers are healthy
docker compose -f docker/docker-compose.yml -p mememory ps

# Or use the CLI
mememory status

Expected output:

Checking http://localhost:4200 ...
OK: 0 memories stored

3. Open the Admin UI

Navigate to http://localhost:4200 in your browser. The web UI lets you browse, search, and manage memories.

Connect an MCP Client

Claude Code

Add the MCP server to your config file (~/.claude/.mcp.json, or .mcp.json in your project root):

{
  "mcpServers": {
    "mememory": {
      "type": "stdio",
      "command": "docker",
      "args": ["exec", "-i", "mememory", "server"],
      "env": {}
    }
  }
}

For automatic session bootstrap, per-turn pinned-rule reinjection, and forced first-recall enforcement, install all four hooks in one command:

mememory install-hooks

This patches ~/.claude/settings.json with SessionStart, UserPromptSubmit, PreToolUse, and PostToolUse hooks. Existing settings are preserved; a backup is written before any change. Run mememory install-hooks --uninstall to remove.

mememory setup also offers to install the hooks at the end of its run if you skipped this step earlier.

See MCP Client Setup for the manual configuration if you prefer to edit settings.json by hand, or Pinned Rules & Forced Recall for what the new hooks actually do.

Claude Desktop

See the full MCP Client Setup guide for Claude Desktop and other clients.

Verify It Works

Once connected, ask your agent to use the memory tools:

Store a test memory: "This is a test memory from getting started"

The agent should call the remember tool and confirm the memory was stored. Then verify:

Recall memories about "test memory"

You should see the memory you just stored, with a relevance score.

Check the Admin UI at http://localhost:4200 to see the memory in the database.

What's Next

• Memory Model — understand memory types, fields, and when to use each
• Scopes & Hierarchy — learn about global and project scopes
• Session Bootstrap — configure automatic memory loading at session start
• Pinned Rules & Forced Recall — per-turn rule reinjection and recall enforcement
• MCP Client Setup — detailed setup for all supported clients