IT-Square-Plus/Yggdrasil

🌳 Yggdrasil MCP Memory Server

Production-ready MCP memory server with Chroma Cloud vector storage.

A modern Model Context Protocol (MCP) server that provides persistent semantic memory using Chroma Cloud vector database. Built with Python, FastAPI, and following Context7 best practices.

ToC

1. Features

2. Architecture

   • Technology Stack
   • Project Structure

3. Quick Start

   • Prerequisites

     • Get Chroma Cloud Credentials
     • Configure Environment
     • Run with Docker
     • Configure Claude Code

4. ToDo

5. Extras

6. FAQ

7. Credits

8. Authors

Features

• MCP Protocol 2025-03-26 - Streamable HTTP transport (stateless)
• Chroma Cloud - CloudClient integration (recommended by Context7)
• Path-Based Routing¹ - Multi-project support with ONE Docker container
• Semantic Search - Vector-based similarity search with ONNX embeddings²
• Tag Management - Organize memories with custom tags and metadata
• Time-Based Queries - Natural language time expressions ("yesterday", "last week")
• Docker Ready - Multi-stage build, non-root user, proper healthchecks
• Production Best Practices - Context7 validated patterns throughout
• 28 MCP Tools - Complete CRUD, search, export, merge, cleanup operations

Architecture

Technology Stack

• Python 3.13
• MCP Server Stack:
  • FastMCP - MCP protocol implementation (2025-03-26)
  • FastAPI - Async web framework
  • Uvicorn - ASGI server
• Chroma Cloud - Vector database for embeddings
• Docker - Containerization platform

Project Structure

Yggdrasil/
├── docs/                       # Documentation
├── [deployment files]          # docker-compose.yml, Dockerfile, pyproject.toml
├── .env.example                # Configuration template
│
└── src/
    ├── server.py               # MCP server stack
    ├── config/                 # Application settings
    │   ├── settings.py
    │   ├── chroma_client.py
    │   └── request_context.py
    ├── services/               # Business logic
    │   └── memory_service.py
    └── utils/                  # Helper functions
        └── time_parser.py

Quick Start

Prerequisites

• Docker (Engine or Desktop)
• Chroma Cloud Account - https://www.trychroma.com
• MCP Client - Claude Code (recommended) or Claude Desktop (not tested)

1. Get Chroma Cloud Credentials

1. Create account Chroma Cloud³ at https://www.trychroma.com
2. Create a new Tenant (your organisation)
3. Create a Database in your tenant
4. Generate an API Key
5. Note down: tenant, database, api_key

2. Configure Environment

# Clone this repository
git clone https://github.com/IT-Square-Plus/Yggdrasil.git

# Navigate to project directory
cd Yggdrasil

# Copy environment template
cp .env.example .env

# Edit .env with your credentials
nano .env

Required variables:

CHROMA_API_KEY=your_api_key_here
CHROMA_TENANT=your_tenant_name
CHROMA_DATABASE=your_database_name
CHROMA_COLLECTION=default_memories  # Used only when URL is /mcp (not /mcp-project_name)

3. Run with Docker

# Build and start
docker compose up --build -d

# Check logs (wait for ONNX model download ~79MB, ~20 seconds)
docker compose logs -f
# You'll see: "🤖 ONNX embedding model successfully downloaded!"

# Check health
curl http://localhost:8080/ready
# Or open in browser: http://localhost:8080/ready
# If you see JSON response, MCP server is running and ONNX model loaded!

Note: First startup downloads ONNX model² (~80MB, ~20 seconds) from Hugging Face and caches it locally.

4. Configure Claude Code

Create a .mcp.json file in your project root:

{
  "mcpServers": {
    "Yggdrasil": {
      "type": "http",
      "url": "http://localhost:8080/mcp-your_project_name",
      "metadata": {
        "description": "Yggdrasil MCP Memory Server"
      }
    }
  }
}

Important:

• Replace your_project_name with your actual project name (e.g., mcp-enigma, mcp-myapp)
• The "type": "http" field is required - without it Claude Code won't connect!
• Each project can have its own .mcp.json with a unique URL suffix for isolated memory

For multi-project setup details, see:

ToDo

• Claude Desktop compatibility (might work, haven't tested it yet)
• [WiP] Document/file parsing
• Gemini CLI compatibility

Extras

If you're wondering about what the Chroma Cloud Quotas (Org Settings -> Quotas) and its values mean?

Have a look at this guide:

FAQ

Credits

• Heavily inspired by Henry "doobidoo" Krupp's MCP Memory Service project.

• Special thanks to Jakub Gościniak for inspiring this project through our discussions about separate MCP Memory.

• Also thanks to Maciej Waśniewski thanks to whom and our shared memory, we can work on the same project.

Authors

• Łukasz Bryzek

📚 Footnotes

Path-Based Routing

Enables one Yggdrasil Docker container to serve multiple Claude Code projects simultaneously, each with isolated memory collections.

For complete setup guide with examples, see:

ONNX Model

Open Neural Network Exchange (ONNX) is ChromaDB's AI engine for semantic search - it converts text into 384/768/1536/3072/4096-dimensional vectors representing meaning, enabling search by concept rather than keywords.

For detailed technical explanation, see:

Chroma Cloud

For full guide on how to set up and configure Chroma Cloud account, see: