MemoryLoom

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.

[](https://github.com/bunnysayzz/memoryloom/actions/workflows/ci.yml) [](LICENSE)

🚀 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](HTTPMCPGUIDE.md) - 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](NOCREDITCARD_DEPLOY.md) - Railway & Fly.io
• [Complete Deployment Guide](DEPLOYMENT_GUIDE.md) - All platforms

---

📚 Documentation

[📑 Complete Documentation Index](DOCUMENTATION_INDEX.md) - Navigate all documentation

• [HTTP MCP Connection Guide](HTTPMCPGUIDE.md) - Connect to remote MemoryLoom instances (Heroku, Railway, etc.)
• [Editor Setup Guide](EDITOR_SETUP.md) - Step-by-step configuration for Claude Desktop, Cursor, VS Code, Windsurf, and Zed
• [Deployment Guide](DEPLOYMENT_GUIDE.md) - Deploy to 10+ platforms with one-click or manual setup
• [No Credit Card Deploy](NOCREDITCARD_DEPLOY.md) - Deploy to Railway or Fly.io without credit card
• [Quick Reference Card](QUICK_REFERENCE.md) - Printable cheat sheet with config locations, commands, and troubleshooting
• [Troubleshooting Guide](TROUBLESHOOTING.md) - Comprehensive solutions for common issues across all editors
• [Migration Guide](MIGRATION_GUIDE.md) - 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](#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](EDITOR_SETUP.md#claude-desktop) - Anthropic's native app
• [Cursor IDE](EDITOR_SETUP.md#cursor-ide) - AI-first code editor
• [VS Code + GitHub Copilot](EDITOR_SETUP.md#vs-code-with-github-copilot) - Microsoft's editor with Copilot
• [Windsurf IDE](EDITOR_SETUP.md#windsurf-ide) - Codeium's Cascade AI editor
• [Zed Editor](EDITOR_SETUP.md#zed-editor) - High-performance collaborative editor

📖 [Complete Editor Setup Guide →](EDITOR_SETUP.md)

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

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

• [ ] Choose your editor - See [Editor Comparison](EDITOR_SETUP.md#editor-comparison)

• [ ] Configure your editor - Follow the guide for your editor:
• [Claude Desktop](EDITOR_SETUP.md#claude-desktop)
• [Cursor](EDITOR_SETUP.md#cursor-ide)
• [VS Code](EDITOR_SETUP.md#vs-code-with-github-copilot)
• [Windsurf](EDITOR_SETUP.md#windsurf-ide)
• [Zed](EDITOR_SETUP.md#zed-editor)

• [ ] Verify installation

``bash 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](QUICK_REFERENCE.md) for easy access

• [ ] Optional: Set up backups

``json { "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](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

Source & license

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

• Author: bunnysayzz
• Source: bunnysayzz/MemoryLoom
• License: MIT

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