MemoryVault MCP

A self-hosted, graph-aware memory server for AI assistants. Built on Cloudflare Workers + D1.

MemoryVault gives AI clients (Claude, ChatGPT, etc.) persistent memory across sessions via the Model Context Protocol (MCP). Store notes, facts, and journal entries. Link related memories into a knowledge graph. Search with hybrid lexical + semantic retrieval.

Features

• 40+ MCP tools — memory CRUD, graph linking, conflict detection, objectives, snapshots, and more
• Hybrid search — lexical + semantic (Vectorize + Workers AI embeddings) with RRF fusion
• Knowledge graph — typed relationships, path finding, neighborhood traversal, inferred links
• Multi-tenant — user accounts with isolated "brains" and per-brain policies
• OAuth + PKCE — standards-based auth for MCP clients, plus legacy bearer token fallback
• Web viewer — browse memories, explore the graph, manage settings at /view
• 6 themes — cyberpunk, light, midnight, solarized, ember, arctic
• Zero external dependencies at runtime (just @modelcontextprotocol/sdk and zod)

Quick Start

1. Clone and install

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

2. Configure secrets

cp .dev.vars.example .dev.vars
# Edit .dev.vars with your own secrets

3. Set up Cloudflare resources

# Create D1 database
npx wrangler d1 create ai-memory

# Update wrangler.toml with your database_id

# Create KV namespace for rate limiting
npx wrangler kv namespace create RATE_LIMIT_KV
# Update wrangler.toml with the KV namespace id

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

4. Initialize database schema

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

5. Run locally

npm run dev

Deploy to Production

# Set 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

Configuration

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

MCP Integration

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. Your client handles the flow automatically.

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

Architecture

Module	Purpose
src/index.ts	Worker entry point and HTTP routing
src/types.ts	Shared TypeScript types
src/constants.ts	Configuration constants
src/utils.ts	Pure utility functions
src/crypto.ts	PBKDF2, JWT, HMAC utilities
src/cors.ts	CORS and security headers
src/db.ts	D1 queries and schema migration
src/auth.ts	Session management and auth endpoints
src/oauth.ts	OAuth protocol (authorization, token, registration)
src/vectorize.ts	Semantic search and Vectorize integration
src/scoring.ts	Dynamic confidence/importance scoring
src/tools-schema.ts	MCP tool definitions and metadata
src/tools.ts	MCP tool handler implementations
src/viewer.ts	Web viewer UI (/view)
src/routes.ts	API and HTML route handlers

Tech stack: Cloudflare Workers, D1 (SQLite), Vectorize, Workers AI (@cf/baai/bge-base-en-v1.5), MCP SDK

Available MCP Tools

Memory operations: memory_save, memory_get, memory_get_fact, memory_search, memory_list, memory_update, memory_delete, memory_reindex, memory_stats

Graph: memory_link, memory_unlink, memory_links, memory_link_suggest, memory_path_find, memory_subgraph, memory_neighbors, memory_graph_stats, memory_tag_stats

Knowledge management: memory_consolidate, memory_forget, memory_activate, memory_reinforce, memory_decay, memory_conflicts, memory_conflict_resolve, memory_entity_resolve

Trust & policy: memory_source_trust_set, memory_source_trust_get, brain_policy_set, brain_policy_get

Snapshots: brain_snapshot_create, brain_snapshot_list, brain_snapshot_restore

Objectives: objective_set, objective_list, objective_next_actions

Observability: memory_changelog, memory_watch, memory_explain_score, tool_manifest, tool_changelog

Development

npm run dev          # Start local worker
npm run type-check   # TypeScript check
npm run deploy       # Deploy to Cloudflare

Smoke test:

ADMIN_TOKEN=... npm run smoke:oauth-isolation

Notes:

• Semantic search requires Workers AI/Vectorize bindings — use npx wrangler dev --remote for full functionality
• Local dev uses --local D1 by default

Contributing

See CONTRIBUTING.md.

License

MIT