MemoryLoom

MemoryLoom is an MCP-compatible memory server for editors, IDEs, and AI clients. It provides persistent memory with a clean tool interface, metadata-aware retrieval, and pluggable storage backends.

🚀 One-Click Deploy

MemoryLoom supports two connection modes:

• stdio MCP (Local only) - Traditional MCP over stdin/stdout for local development
• HTTP MCP (Local or Remote) - MCP over HTTP for remote deployments

📖 HTTP MCP Connection Guide - Connect to remote MemoryLoom instances

💡 Recommendation:

• Local development: Use stdio MCP with node server.js
• Remote/Team use: Deploy to Railway, Fly.io, Heroku, or Render and use HTTP MCP
• Full MCP support: Avoid serverless platforms (Vercel, Netlify) - they don't support persistent connections

📖 Deployment Guides:

• No Credit Card Deploy Guide - Railway & Fly.io
• Complete Deployment Guide - All platforms

---

📚 Documentation

📑 Complete Documentation Index - Navigate all documentation

• HTTP MCP Connection Guide - Connect to remote MemoryLoom instances (Heroku, Railway, etc.)
• Editor Setup Guide - Step-by-step configuration for Claude Desktop, Cursor, VS Code, Windsurf, and Zed
• Deployment Guide - Deploy to 10+ platforms with one-click or manual setup
• No Credit Card Deploy - Deploy to Railway or Fly.io without credit card
• Quick Reference Card - Printable cheat sheet with config locations, commands, and troubleshooting
• Troubleshooting Guide - Comprehensive solutions for common issues across all editors
• Migration Guide - Migrate from other memory servers, switch storage modes, team setup
• API Documentation (MemoryLoom_Documentation.txt) - Complete API reference, tool schemas, and usage examples
• Quick Start - Get running in 2 minutes

🏗️ Architecture

┌─────────────────────────────────────────────────────────────┐
│                    MCP-Compatible Editors                    │
│  Claude Desktop │ Cursor │ VS Code │ Windsurf │ Zed         │
└────────────────────────┬────────────────────────────────────┘
                         │ MCP Protocol (stdio)
                         ▼
┌─────────────────────────────────────────────────────────────┐
│                      MemoryLoom Server                       │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
│  │ Tool Handler │  │ Search Engine│  │ Auth & Rate  │      │
│  │ (10 tools)   │  │ (Hybrid)     │  │ Limiting     │      │
│  └──────────────┘  └──────────────┘  └──────────────┘      │
└────────────────────────┬────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────────┐
│                    Storage Layer (Pluggable)                 │
│  ┌──────────────────────┐    ┌──────────────────────┐       │
│  │   JSON Store         │    │   Postgres Store     │       │
│  │ • File-backed        │    │ • Database-backed    │       │
│  │ • Atomic writes      │    │ • Transactional      │       │
│  │ • Rolling backups    │    │ • Scalable           │       │
│  └──────────────────────┘    └──────────────────────┘       │
└─────────────────────────────────────────────────────────────┘

Features

• MCP server over stdio in server.js
• Memory lifecycle tools:
  • add_memory
  • search_memories
  • get_memories
  • list_memories
  • update_memory
  • delete_memory
  • memory_stats
  • server_status
  • upsert_memory
  • consolidate_memories
• Hybrid ranking with token overlap + embedding similarity + metadata weighting
• Rich memory metadata for filtering and governance

⚠️ Embedding Limitations

MemoryLoom uses a toy-grade character n-gram hashing implementation for embedding similarity, not a production-grade vector embedding model like OpenAI embeddings or sentence-transformers. This is a lightweight, dependency-free approach suitable for:

• Small to medium memory sets (< 10,000 memories)
• Simple semantic matching based on character patterns
• Zero external dependencies and API keys
• Fast local computation

Limitations:

• Not a true semantic embedding (no word context understanding)
• Performance degrades with larger memory sets
• May not capture complex semantic relationships
• Character-based matching can miss synonyms or related concepts

For production use with large memory sets or advanced semantic understanding, consider integrating a proper vector embedding service (e.g., OpenAI embeddings, sentence-transformers) and a vector database.

• Pluggable storage:
  • json mode (local file-backed)
  • postgres mode (database-backed)
• Runtime configuration via environment variables
• Optional API-key protection for MCP tool calls
• Optional health/readiness HTTP endpoints for deployment platforms
• Optional hosted web UI on / (modern animated responsive landing page)
• Atomic writes and optional rolling backups in JSON mode
• Docker + Compose deployment support
• End-to-end verification script

Quick Start

npm install
npm run setup
npm run verify
npm start

Editor Setup

MemoryLoom works with all major MCP-compatible editors and AI clients.

Connection Modes

stdio MCP (Local) - For local development:

{
  "mcpServers": {
    "memoryloom": {
      "command": "node",
      "args": ["/absolute/path/to/memoryloom/server.js"]
    }
  }
}

HTTP MCP (Remote) - For hosted instances:

{
  "mcpServers": {
    "memoryloom": {
      "url": "https://your-app.herokuapp.com/mcp",
      "headers": {
        "Authorization": "Bearer your-api-key"
      }
    }
  }
}

Supported Editors

• Claude Desktop - Anthropic's native app
• Cursor IDE - AI-first code editor
• VS Code + GitHub Copilot - Microsoft's editor with Copilot
• Windsurf IDE - Codeium's Cascade AI editor
• Zed Editor - High-performance collaborative editor

📖 Complete Editor Setup Guide →

Runtime Configuration

Environment variables:

• MEMORYLOOM_STORAGE_MODE: json or postgres
• MEMORYLOOM_DATA_DIR: base directory for local storage
• MEMORYLOOM_DATA_FILE: exact JSON file path (JSON mode)
• MEMORYLOOM_LOG_LEVEL: debug, info, warn, error
• MEMORYLOOM_BACKUP_ON_WRITE: true or false
• MEMORYLOOM_BACKUP_RETENTION: number of backup snapshots retained
• MEMORYLOOM_POSTGRES_URL: Postgres connection string for postgres mode
• MEMORYLOOM_API_KEY: optional API key required for all tool calls
• MEMORYLOOM_HEALTH_PORT: optional HTTP port exposing /health and /ready
• MEMORYLOOM_MAX_TOOL_CALLS_PER_MINUTE: optional global per-minute tool call limit (0 disables)
• MEMORYLOOM_WEB_UI: set to false to disable hosted web UI routes

Reference defaults:

• .env.example

Storage Modes

JSON Mode

export MEMORYLOOM_STORAGE_MODE=json
npm start

Postgres Mode

export MEMORYLOOM_STORAGE_MODE=postgres
export MEMORYLOOM_POSTGRES_URL=postgres://postgres:postgres@localhost:5432/memoryloom
npm start

On startup in Postgres mode, MemoryLoom auto-creates the memoryloom_memories table if it does not exist.

Health Endpoints

export MEMORYLOOM_HEALTH_PORT=8080
npm start

Endpoints:

• GET /health
• GET /ready
• GET / (web UI, when MEMORYLOOM_WEB_UI is not false)

Tool Payloads

add_memory

{
  "api_key": "your-api-key-if-enabled",
  "content": "User prefers concise technical responses with examples.",
  "importance": 0.95,
  "metadata": {
    "user": "u-1042",
    "project": "memoryloom",
    "memory_type": "preference",
    "tags": ["style", "format"],
    "confidence": 0.99
  }
}

search_memories

{
  "api_key": "your-api-key-if-enabled",
  "query": "response style preference",
  "filters": {
    "user": "u-1042",
    "project": "memoryloom",
    "memory_type": "preference"
  },
  "limit": 5
}

update_memory

{
  "api_key": "your-api-key-if-enabled",
  "id": "memory-id",
  "content": "Updated memory content",
  "metadata": {
    "tags": ["updated"],
    "confidence": 0.98
  }
}

delete_memory

{
  "api_key": "your-api-key-if-enabled",
  "id": "memory-id",
  "hard_delete": false
}

memory_stats

{
  "api_key": "your-api-key-if-enabled"
}

server_status

{
  "api_key": "your-api-key-if-enabled"
}

upsert_memory

{
  "api_key": "your-api-key-if-enabled",
  "content": "The latest user preference statement",
  "metadata": {
    "user": "u-1042",
    "project": "memoryloom",
    "memory_type": "preference",
    "tags": ["style"]
  }
}

consolidate_memories

{
  "api_key": "your-api-key-if-enabled",
  "minimum_count": 3,
  "archive_originals": true,
  "filters": {
    "project": "memoryloom",
    "memory_type": "note"
  }
}

Deployment Files

Container Platforms

• Dockerfile - Docker container configuration
• docker-compose.yml - Docker Compose for local development
• app.json - Heroku app manifest
• render.yaml - Render blueprint
• railway.json - Railway configuration
• fly.toml - Fly.io app configuration
• .do/app.yaml - DigitalOcean App Platform configuration
• Procfile - Process file for Heroku/similar platforms

Cloud Platforms

• cloudbuild.yaml - Google Cloud Build & Cloud Run
• azure-pipelines.yml - Azure Container Apps deployment

Serverless Platforms (Limited MCP Support)

• vercel.json - Vercel configuration
• netlify.toml - Netlify configuration
• netlify/functions/api.js - Netlify Functions wrapper

Recommended: Use container platforms (Heroku, Render, Railway, Fly.io, Koyeb, DigitalOcean) for full MCP stdio support.

Verification

Run:

npm run verify

This validates MCP initialization, tool discovery, add/search/update/list/get flows, archive + hard delete behavior, metadata/timestamp behavior, embeddings, and status/stats responses.

---

🚀 Getting Started Checklist

New to MemoryLoom? Follow this checklist:

• Install MemoryLoom

  git clone https://github.com/bunnysayzz/memoryloom.git
  cd memoryloom
  npm install
  npm run setup

• Choose your editor - See Editor Comparison

• Configure your editor - Follow the guide for your editor:

  • Claude Desktop
  • Cursor
  • VS Code
  • Windsurf
  • Zed

• Verify installation

  npm run verify

• Test in your editor

  • Ask your AI: "Store a memory that I prefer dark mode"
  • Ask your AI: "What preferences have I stored?"

• Bookmark the Quick Reference for easy access

• Optional: Set up backups

  {
    "env": {
      "MEMORYLOOM_BACKUP_ON_WRITE": "true",
      "MEMORYLOOM_BACKUP_RETENTION": "10"
    }
  }

---

💡 Usage Examples

Store User Preferences

You: Remember that I prefer TypeScript over JavaScript for new projects

AI: [Uses add_memory tool]
✓ Stored: "User prefers TypeScript over JavaScript for new projects"

Retrieve Context

You: What are my programming language preferences?

AI: [Uses search_memories tool]
Based on your memories, you prefer:
- TypeScript over JavaScript for new projects
- Python for data analysis
- Go for backend services

Project-Specific Memory

You: For the "acme-app" project, remember we're using PostgreSQL and Redis

AI: [Uses add_memory with project metadata]
✓ Stored with project: acme-app

Search by Project

You: What tech stack are we using for acme-app?

AI: [Uses search_memories with project filter]
For acme-app, you're using:
- Database: PostgreSQL
- Cache: Redis
- Framework: Next.js

---

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

---

📄 License

MIT License - see LICENSE file for details.

---

🔗 Links

• GitHub: github.com/bunnysayzz/memoryloom
• Issues: Report a bug or request a feature
• MCP Protocol: Model Context Protocol Specification

---

Built with ❤️ for the MCP community