🌳 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: docs/PATH_BASED_ROUTING.md

---

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: docs/CHROMA_QUOTAS.md

---

FAQ

Does it work on Open AI's Codex?

Not sure. Haven't tested and have no intention to work on Codex's compatibility yet. It's the lowest priotity now for me.

Might work out-of-the-box, might not. Not a Codex user, sorry.

Why only Chroma Cloud and not self-hosted ChromaDB?

I actually developed previously Yggdrasil using self-hosted ChromaDB 0.6.x so you could run it on your own server.

But then ChromaDB Devs released new version of ChromaDB rewritten in Rust and they haven't implemented Auth mechanism yet.

I was kind of too lazy to implement any sort of OAuth for 1.x and then I've discovered that they're providing Chroma Cloud.

It's damn cheap. No monthly contract, just pay-as-you-go model. You pay for what you use and API Auth included so why not?

---

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

[1] 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: docs/PATH_BASED_ROUTING.md

[2] 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: docs/ONNX.md

[3] Chroma Cloud

For full guide on how to set up and configure Chroma Cloud account, see: docs/CHROMA_CLOUD.md