# Memoryvault

> MemoryVault — a self-hosted, graph-aware memory server for AI assistants. Cloudflare Workers + D1 + MCP.

- **Type:** MCP server
- **Install:** `agentstack add mcp-guirguispierre-memoryvault`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [guirguispierre](https://agentstack.voostack.com/s/guirguispierre)
- **Installs:** 0
- **Category:** [Cloud & Infrastructure](https://agentstack.voostack.com/c/cloud-infrastructure)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [guirguispierre](https://github.com/guirguispierre)
- **Source:** https://github.com/guirguispierre/memoryvault

## Install

```sh
agentstack add mcp-guirguispierre-memoryvault
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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)](https://modelcontextprotocol.io). 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**

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

2. **Configure secrets**

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

3. **Set up Cloudflare resources**

```bash
# 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**

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

5. **Run locally**

```bash
npm run dev
```

## Deploy to Production

```bash
# 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

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

**Smoke test:**
```bash
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](https://github.com/guirguispierre)
- **Source:** [guirguispierre/memoryvault](https://github.com/guirguispierre/memoryvault)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-guirguispierre-memoryvault
- Seller: https://agentstack.voostack.com/s/guirguispierre
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.