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)

Related MCP server: MCP Memento

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

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

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