Memoryvault

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

1. Configure secrets

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

1. 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

1. Initialize database schema

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

1. 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://..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 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](./CONTRIBUTING.md).

License

[MIT](./LICENSE)

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: guirguispierre
• Source: guirguispierre/memoryvault
• License: MIT

Install and usage instructions live in the source repository linked above.