Getting Started

Getting Started

Prerequisites

• Node.js 20+
• Wrangler CLI (npm install -g wrangler)
• A free Cloudflare account

Installation

git clone https://github.com/guirguispierre/memoryvault.git
cd memoryvault
npm install

Configuration

Secrets

Copy the example file and fill in your own values:

cp .dev.vars.example .dev.vars

Variable	Required	Description
AUTH_SECRET	Yes	Signs JWTs and secures legacy bearer auth. Use a long random string (32+ chars).
ADMIN_TOKEN	Yes	Required for POST /register (OAuth client registration). Use a separate long random string.
OAUTH_REDIRECT_DOMAIN_ALLOWLIST	No	Comma-separated hostnames allowed for OAuth redirect URIs. localhost and 127.0.0.1 are always allowed.

Cloudflare Resources

Create the required Cloudflare resources:

# Create D1 database
npx wrangler d1 create ai-memory

# Create KV namespace for rate limiting
npx wrangler kv namespace create RATE_LIMIT_KV

# Create Vectorize index (for semantic search)
npx wrangler vectorize create ai-memory-semantic-v1 --dimensions=768 --metric=cosine

After creating each resource, update wrangler.toml with the IDs printed by each command:

[[d1_databases]]
binding = "DB"
database_name = "ai-memory"
database_id = "<your-database-id>"

[[kv_namespaces]]
binding = "RATE_LIMIT_KV"
id = "<your-kv-namespace-id>"

Initialize Database

npx wrangler d1 execute ai-memory --local --file=schema.sql

Local Development

npm run dev

This starts a local Wrangler dev server at http://127.0.0.1:8787.

Notes:

• Semantic search requires Workers AI/Vectorize bindings. Use npx wrangler dev --remote for full semantic functionality.
• Local dev uses an in-memory D1 database by default.

Deploy to Production

# Set production secrets
npx wrangler secret put AUTH_SECRET
npx wrangler secret put ADMIN_TOKEN

# Apply schema to remote D1
npx wrangler d1 execute ai-memory --remote --file=schema.sql

# Deploy
npm run deploy

Your worker will be live at https://<worker-name>.<your-subdomain>.workers.dev.

Connect an MCP Client

Point your MCP client to:

https://<your-worker>.<your-subdomain>.workers.dev/mcp

OAuth mode (recommended): Leave the API key empty. The server responds with OAuth discovery metadata and your client handles the flow automatically.

Legacy bearer mode: Send Authorization: Bearer <AUTH_SECRET> for simple setups.

Verify It Works

Visit your worker URL in a browser. You should see the MemoryVault Dev Portal landing page with links to the MCP endpoint, web viewer, and OAuth metadata.

Visit /view to open the web viewer and log in.