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

- **Type:** MCP server
- **Install:** `agentstack add mcp-bunnysayzz-memoryloom`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [bunnysayzz](https://agentstack.voostack.com/s/bunnysayzz)
- **Installs:** 0
- **Category:** [Search](https://agentstack.voostack.com/c/search)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [bunnysayzz](https://github.com/bunnysayzz)
- **Source:** https://github.com/bunnysayzz/MemoryLoom

## Install

```sh
agentstack add mcp-bunnysayzz-memoryloom
```

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

## About

# 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](HTTP_MCP_GUIDE.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](NO_CREDIT_CARD_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](HTTP_MCP_GUIDE.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](NO_CREDIT_CARD_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

```bash
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:
```json
{
  "mcpServers": {
    "memoryloom": {
      "command": "node",
      "args": ["/absolute/path/to/memoryloom/server.js"]
    }
  }
}
```

**HTTP MCP (Remote)** - For hosted instances:
```json
{
  "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

```bash
export MEMORYLOOM_STORAGE_MODE=json
npm start
```

### Postgres Mode

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

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

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

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

### `update_memory`

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

### `delete_memory`

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

### `memory_stats`

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

### `server_status`

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

### `upsert_memory`

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

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

```bash
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](https://github.com/bunnysayzz/memoryloom)
- **Issues:** [Report a bug or request a feature](https://github.com/bunnysayzz/memoryloom/issues)
- **MCP Protocol:** [Model Context Protocol Specification](https://modelcontextprotocol.io)

---

**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](https://github.com/bunnysayzz)
- **Source:** [bunnysayzz/MemoryLoom](https://github.com/bunnysayzz/MemoryLoom)
- **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:** yes
- **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-bunnysayzz-memoryloom
- Seller: https://agentstack.voostack.com/s/bunnysayzz
- 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%.