Installation

This tutorial sets up the two deployment profiles by hand. Both run on PostgreSQL alone (pgvector included); they differ only in whether the multi-tenant auth stack is wired. For the one-command path, see the quick start.

All commands run from the repository root. If pnpm is not on your PATH, replace the leading pnpm with npm exec --yes pnpm@11.5.0 --.

Standard profile (default)

The standard profile is the default and the primary production target. It adds JWT sessions, per-agent API keys, organizations, and Postgres-backed rate limiting on top of the shared storage. Hybrid lexical + semantic retrieval is enabled out of the box, and the full reindex / queue / cancel / retry maintenance tool set is exposed.

pnpm install
test -f .env || cp .env.example .env
pnpm docker:up
pnpm db:generate
pnpm db:migrate:deploy
pnpm build
pnpm --filter mcp-server dev

Open a second terminal and verify the server:

curl http://localhost:3000/health

The health response reports ok when the process and PostgreSQL are ready.

Lite profile (single-user)

The lite profile is a single-user variant with the same durable Postgres storage as standard, minus the auth/organization stack — there is no login or API-key surface to configure. Set DEPLOYMENT_PROFILE=lite on the build and dev commands:

pnpm install
test -f .env || cp .env.example .env
pnpm docker:up
pnpm db:generate
pnpm db:migrate:deploy
DEPLOYMENT_PROFILE=lite pnpm build
DEPLOYMENT_PROFILE=lite pnpm --filter mcp-server dev

Moving a lite deployment up to standard later needs no data migration — both use the same Postgres tables. Switch the profile and provide the auth configuration (AUTH_REQUIRED, JWT_SECRET, API keys); see MCP client setup.

Embeddings (local by default)

Semantic recall needs an embedding provider; the default is Ollama (EMBEDDING_PROVIDER=ollama) — local, no API key. Either install Ollama on the host (ollama.com/download) and pull the default model:

ollama pull nomic-embed-text

or start the opt-in compose profile:

docker compose --profile ollama up -d
docker compose exec ollama ollama pull nomic-embed-text

To use OpenAI instead, set EMBEDDING_PROVIDER=openai and OPENAI_API_KEY in .env. Without a reachable provider, writes still succeed — memories are stored without vectors and backfilled by a later reindex (Configure embeddings).

Start specific workspaces

Run one workspace at a time during local development.

Workspace	Command	Default URL
MCP server	pnpm --filter mcp-server dev	http://localhost:3000
Web app	pnpm --filter web dev	http://localhost:3000
Docs app	pnpm --filter docs dev	http://localhost:3001

The MCP server and web app both use port 3000 by default, so do not run those two commands at the same time unless you change PORT for one of them.

Local infrastructure

Docker Compose starts the PostgreSQL container used by the MCP server.

Task	Command
Start services and wait	pnpm docker:up
Show service status	pnpm docker:ps
Tail service logs	pnpm docker:logs
Restart services	pnpm docker:restart
Stop services and keep data	pnpm docker:down
Stop services and delete data	pnpm docker:clean

Default host ports:

Service	Environment setting	Default
PostgreSQL	POSTGRES_PORT	5432
Ollama (optional)	OLLAMA_PORT	11434

If Docker reports that a port is already allocated, edit .env before starting services. Keep each service URL aligned with the host port. For example, POSTGRES_PORT=5433 also needs DATABASE_URL to use localhost:5433.

Database commands

Task	Command
Generate Prisma client	pnpm db:generate
Deploy migrations (unattended)	pnpm db:migrate:deploy
Create and run a development migration	pnpm db:migrate
Push schema without a migration	pnpm db:push
Reset the local database	pnpm db:reset
Open Prisma Studio	pnpm db:studio

Use pnpm db:migrate:deploy to apply committed migrations unattended (the installer does this). Use pnpm db:migrate when authoring a new schema change, and pnpm db:push only for short-lived local experiments.

Recovery

For a single-node local stack, reset by clearing the database volume and re-migrating:

pnpm docker:clean
pnpm docker:up
pnpm db:migrate:deploy

If the vector store drifted from Postgres (embeddings missing or stale), reindex from the source of truth:

MCP_ADMIN_TOKEN="$MCP_ADMIN_TOKEN" \
  pnpm --filter mcp-server reindex

The CLI is cursor-resumable; pass --cursor <id> to continue from a previous run.

Troubleshooting

Check Docker service health:

pnpm docker:ps
pnpm docker:logs

Regenerate Prisma after schema or dependency changes:

pnpm db:generate

Check server health directly:

curl http://localhost:3000/health

Next steps

• Store your first memory
• MCP client setup
• Deploy to production with the hardened Docker image.