Local Development

Full local setup and testing workflow for API, CLI, MCP, and database

Local Development

Use this page for local setup plus full testing flow: web app, API, CLI, MCP, DB, and reset/recovery.

Prerequisites

Node.js 20+
pnpm
Docker Desktop (or Docker Engine + Compose)

1) Start the stack

git clone https://github.com/memctl/memctl.git
cd memctl
cp .env.example .env
docker compose up -d
docker compose exec web pnpm db:push

Open http://localhost:3000.

2) Configure auth for local use

If you do not want to configure GitHub OAuth, use dev bypass.

Set these in .env:

DEV_AUTH_BYPASS=true
NEXT_PUBLIC_DEV_AUTH_BYPASS=true
DEV_AUTH_BYPASS_ORG_SLUG=dev-org
NEXT_PUBLIC_DEV_AUTH_BYPASS_ORG_SLUG=dev-org
[email protected]
DEV_AUTH_BYPASS_USER_NAME=Dev User

3) Verify services are healthy

curl -sS http://localhost:3000/api/v1/health
curl -sS http://localhost:8080/v1/health

Expected: both endpoints return a healthy response.

4) Create a local API token

From the dashboard:

Sign in at http://localhost:3000/login
Open your org
Go to token settings
Create token

5) Test CLI against local API

export MEMCTL_TOKEN=your-local-token
export MEMCTL_ORG=dev-org
export MEMCTL_PROJECT=your-project
export MEMCTL_API_URL=http://localhost:3000/api/v1

Run a quick CLI smoke test:

node packages/cli/dist/index.js doctor
node packages/cli/dist/index.js capacity
node packages/cli/dist/index.js list
node packages/cli/dist/index.js search "test"

6) Test API endpoints directly

# List memories
curl -sS "http://localhost:3000/api/v1/memories?limit=5" \
  -H "Authorization: Bearer $MEMCTL_TOKEN"

# Store a memory
curl -sS -X POST "http://localhost:3000/api/v1/memories" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $MEMCTL_TOKEN" \
  -d '{"key":"dev/test","content":"hello local","scope":"project"}'

7) Test MCP locally (`memctl` server)

Example MCP config:

{
  "mcpServers": {
    "memctl": {
      "command": "node",
      "args": ["/absolute/path/to/memctl/packages/cli/dist/index.js"],
      "env": {
        "MEMCTL_TOKEN": "your-local-token",
        "MEMCTL_API_URL": "http://localhost:3000/api/v1",
        "MEMCTL_ORG": "dev-org",
        "MEMCTL_PROJECT": "your-project"
      }
    }
  }
}

Restart your MCP client/IDE after editing config.

8) Run automated tests

# Entire repo
pnpm test

# Specific package examples
pnpm --filter memctl test
pnpm --filter @memctl/shared test

# Watch mode example
pnpm --filter memctl test -- --watch

9) DB operations you will use often

# Push schema after schema.ts changes
docker compose exec web pnpm db:push

# Generate migrations
docker compose exec web pnpm db:generate

# Run migrations
docker compose exec web pnpm db:migrate

# Open Drizzle Studio
TURSO_DATABASE_URL=http://localhost:8080 TURSO_AUTH_TOKEN= pnpm --filter @memctl/db dlx drizzle-kit studio

10) Optional: Stripe webhook local testing

# In .env set STRIPE_SECRET_KEY=sk_test_...
docker compose --profile tools up -d

11) Production-like local run

docker compose -f docker-compose.prod.yml up --build

12) Clean reset

docker compose down -v
docker compose up --build -d
docker compose exec web pnpm db:push

Troubleshooting

For deeper troubleshooting, see:

docs/local-development.md
docs/testing-environment.md
docs/troubleshooting.md

Local Development

Use this page for local setup plus full testing flow: web app, API, CLI, MCP, DB, and reset/recovery.

Prerequisites

Node.js 20+
pnpm
Docker Desktop (or Docker Engine + Compose)

1) Start the stack

git clone https://github.com/memctl/memctl.git
cd memctl
cp .env.example .env
docker compose up -d
docker compose exec web pnpm db:push

Open http://localhost:3000.

2) Configure auth for local use

If you do not want to configure GitHub OAuth, use dev bypass.

Set these in .env:

DEV_AUTH_BYPASS=true
NEXT_PUBLIC_DEV_AUTH_BYPASS=true
DEV_AUTH_BYPASS_ORG_SLUG=dev-org
NEXT_PUBLIC_DEV_AUTH_BYPASS_ORG_SLUG=dev-org
[email protected]
DEV_AUTH_BYPASS_USER_NAME=Dev User

3) Verify services are healthy

curl -sS http://localhost:3000/api/v1/health
curl -sS http://localhost:8080/v1/health

Expected: both endpoints return a healthy response.

4) Create a local API token

From the dashboard:

Sign in at http://localhost:3000/login
Open your org
Go to token settings
Create token

5) Test CLI against local API

export MEMCTL_TOKEN=your-local-token
export MEMCTL_ORG=dev-org
export MEMCTL_PROJECT=your-project
export MEMCTL_API_URL=http://localhost:3000/api/v1

Run a quick CLI smoke test:

node packages/cli/dist/index.js doctor
node packages/cli/dist/index.js capacity
node packages/cli/dist/index.js list
node packages/cli/dist/index.js search "test"

6) Test API endpoints directly

# List memories
curl -sS "http://localhost:3000/api/v1/memories?limit=5" \
  -H "Authorization: Bearer $MEMCTL_TOKEN"

# Store a memory
curl -sS -X POST "http://localhost:3000/api/v1/memories" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $MEMCTL_TOKEN" \
  -d '{"key":"dev/test","content":"hello local","scope":"project"}'

7) Test MCP locally (`memctl` server)

Example MCP config:

{
  "mcpServers": {
    "memctl": {
      "command": "node",
      "args": ["/absolute/path/to/memctl/packages/cli/dist/index.js"],
      "env": {
        "MEMCTL_TOKEN": "your-local-token",
        "MEMCTL_API_URL": "http://localhost:3000/api/v1",
        "MEMCTL_ORG": "dev-org",
        "MEMCTL_PROJECT": "your-project"
      }
    }
  }
}

Restart your MCP client/IDE after editing config.

8) Run automated tests

# Entire repo
pnpm test

# Specific package examples
pnpm --filter memctl test
pnpm --filter @memctl/shared test

# Watch mode example
pnpm --filter memctl test -- --watch

9) DB operations you will use often

# Push schema after schema.ts changes
docker compose exec web pnpm db:push

# Generate migrations
docker compose exec web pnpm db:generate

# Run migrations
docker compose exec web pnpm db:migrate

# Open Drizzle Studio
TURSO_DATABASE_URL=http://localhost:8080 TURSO_AUTH_TOKEN= pnpm --filter @memctl/db dlx drizzle-kit studio

10) Optional: Stripe webhook local testing

# In .env set STRIPE_SECRET_KEY=sk_test_...
docker compose --profile tools up -d

11) Production-like local run

docker compose -f docker-compose.prod.yml up --build

12) Clean reset

docker compose down -v
docker compose up --build -d
docker compose exec web pnpm db:push

Troubleshooting

For deeper troubleshooting, see:

docs/local-development.md
docs/testing-environment.md
docs/troubleshooting.md

Local Development

Local Development

Prerequisites

1) Start the stack

2) Configure auth for local use

3) Verify services are healthy

4) Create a local API token

5) Test CLI against local API

6) Test API endpoints directly

7) Test MCP locally (`memctl` server)

8) Run automated tests

9) DB operations you will use often

10) Optional: Stripe webhook local testing

11) Production-like local run

12) Clean reset

Troubleshooting

On this page

Local Development

Local Development

Prerequisites

1) Start the stack

2) Configure auth for local use

3) Verify services are healthy

4) Create a local API token

5) Test CLI against local API

6) Test API endpoints directly

7) Test MCP locally (`memctl` server)

8) Run automated tests

9) DB operations you will use often

10) Optional: Stripe webhook local testing

11) Production-like local run

12) Clean reset

Troubleshooting

On this page