Memory MCP Worker
Cloudflare Worker implementing MCP protocol for cross-device memory/knowledge graph access.
Features
- MCP Protocol Support: Works with Claude Code via HTTP transport
- REST API: Access from mobile apps, desktop apps, n8n workflows
- D1 Database: SQLite-based persistent storage
- Full-text Search: Search across all observations
Quick Start
1. Install Dependencies
npm install
2. Create D1 Database
# Create the database
wrangler d1 create memory-graph
# Copy the database_id from output to wrangler.toml
3. Run Migrations
# Local development
npm run db:migrate:local
# Production
npm run db:migrate
4. Deploy
npm run deploy
5. Set API Key Secret
# Generate an API key
openssl rand -base64 32 | tr -d '/+=' | head -c 32
# Add as secret
echo "YOUR_API_KEY" | npx wrangler secret put API_KEY
6. Configure Claude Code
Add to your ~/.claude/settings.json or .mcp.json:
{
"mcpServers": {
"memory-remote": {
"type": "http",
"url": "https://memory-mcp.45black-limited.workers.dev/mcp",
"headers": {
"X-API-Key": "YOUR_API_KEY"
}
}
}
}
Migrating from Local Memory
-
Export your local memory:
claude -p "Use mcp__memory__read_graph and output the raw JSON result" > scripts/local-memory.json -
Run migration:
npx ts-node scripts/migrate-local-memory.ts
API Endpoints
REST API (for apps)
| Endpoint | Method | Description |
|---|---|---|
/api/entities | GET | List all entities |
/api/entities/:name | GET | Get entity with observations |
/api/entities | POST | Create entity |
/api/entities/:name/observations | POST | Add observations |
/api/relations | GET | List all relations |
/api/relations | POST | Create relation |
/api/search?q= | GET | Search entities and observations |
/api/graph | GET | Get full graph |
/api/import | POST | Bulk import |
MCP Protocol
| Endpoint | Method | Description |
|---|---|---|
/mcp | POST | MCP JSON-RPC requests |
/mcp/sse | GET | SSE connection for MCP |
MCP Tools Available
create_entities- Create new entitiescreate_relations- Create relations between entitiesadd_observations- Add observations to entitiesread_graph- Read entire knowledge graphsearch_nodes- Search by queryopen_nodes- Get specific nodes by namedelete_entities- Delete entitiesdelete_relations- Delete relations
Authentication
All /api/* and /mcp/* endpoints require authentication via API key.
Headers supported:
X-API-Key: YOUR_API_KEYAuthorization: Bearer YOUR_API_KEY
The health check endpoint (/) is public.
Mobile App Integration
Example fetch from a mobile app:
const API_KEY = 'YOUR_API_KEY';
const BASE_URL = 'https://memory-mcp.45black-limited.workers.dev';
const headers = {
'Content-Type': 'application/json',
'X-API-Key': API_KEY,
};
// Search for a project
const response = await fetch(`${BASE_URL}/api/search?q=Household%20Planner`, { headers });
const data = await response.json();
// Add an observation
await fetch(`${BASE_URL}/api/entities/Household%20Planner/observations`, {
method: 'POST',
headers,
body: JSON.stringify({
contents: ['Added new budget category feature']
})
});
n8n Integration
An n8n workflow is included for querying the Memory API via webhooks.
Setup
- Import
n8n-workflow-memory-api.jsoninto n8n - Create a "Header Auth" credential:
- Name:
Memory MCP API Key - Header Name:
X-API-Key - Header Value:
YOUR_API_KEY
- Name:
- Assign the credential to all three HTTP Request nodes
- Activate the workflow
Endpoints
Search - POST to /webhook/memory-search:
curl -X POST https://your-n8n-instance/webhook/memory-search \
-H "Content-Type: application/json" \
-d '{"query": "Household Planner"}'
Get Entity - POST to /webhook/memory-entity:
curl -X POST https://your-n8n-instance/webhook/memory-entity \
-H "Content-Type: application/json" \
-d '{"name": "Household Planner"}'
Get Full Graph - POST to /webhook/memory-graph:
curl -X POST https://your-n8n-instance/webhook/memory-graph \
-H "Content-Type: application/json" \
-d '{}'
Create Entity - POST to /webhook/memory-create:
curl -X POST https://your-n8n-instance/webhook/memory-create \
-H "Content-Type: application/json" \
-d '{"name": "My Project", "entityType": "Project", "observations": ["First observation"]}'
Add Observations - POST to /webhook/memory-observations:
curl -X POST https://your-n8n-instance/webhook/memory-observations \
-H "Content-Type: application/json" \
-d '{"name": "My Project", "contents": ["New observation 1", "New observation 2"]}'
Create Relation - POST to /webhook/memory-relations:
curl -X POST https://your-n8n-instance/webhook/memory-relations \
-H "Content-Type: application/json" \
-d '{"from": "Project A", "to": "Project B", "relationType": "depends_on"}'
Delete Entity - POST to /webhook/memory-delete:
curl -X POST https://your-n8n-instance/webhook/memory-delete \
-H "Content-Type: application/json" \
-d '{"name": "Entity Name"}'
Delete Relation - POST to /webhook/memory-delete-relation:
curl -X POST https://your-n8n-instance/webhook/memory-delete-relation \
-H "Content-Type: application/json" \
-d '{"from": "Entity A", "to": "Entity B", "relationType": "relation_type"}'
Development
# Start local dev server
npm run dev
# Typecheck
npm run typecheck
Architecture
┌─────────────────────────────────────────┐
│ Cloudflare Worker │
│ memory-mcp.45black.workers.dev │
├─────────────────────────────────────────┤
│ Hono Framework │
│ ├── /api/* → REST API │
│ └── /mcp → MCP Protocol │
├─────────────────────────────────────────┤
│ Cloudflare D1 (SQLite) │
│ ├── entities │
│ ├── observations │
│ ├── relations │
│ └── observations_fts (full-text) │
└─────────────────────────────────────────┘
