Skip to content
memorylayer.ai Documentation

Installation

Server Installation

The MemoryLayer server is a Python FastAPI application that provides the REST API and MCP server.

Basic Installation

Terminal window
pip install memorylayer-server

With Embedding Providers

Choose an embedding provider based on your needs:

Terminal window
# OpenAI embeddings (cloud)
pip install memorylayer-server[openai]


# Google GenAI embeddings (cloud)
pip install memorylayer-server[google]


# Both cloud embedding providers
pip install memorylayer-server[embeddings]


# All optional dependencies (cloud embeddings + LLMs + document parsers)
pip install memorylayer-server[all]

For self-hosted embeddings, install the separate memorylayer-embed-server peer (text on CPU/GPU, multi-vector and multimodal models):

Terminal window
pip install "memorylayer-embed-server[local]"  # CPU-friendly sentence-transformers
pip install "memorylayer-embed-server[gpu]"    # multi-vector / multimodal (OCR, vLLM, ColPali)
pip install "memorylayer-embed-server[all]"    # everything
memorylayer-embed serve --port 61051

The peer’s default single-vector provider is sentence_transformers, which ships in the [local] extra — install that (or [all]) unless you are overriding the provider. [gpu] covers the multi-vector and multimodal models only.

The core server’s own default embedding provider is hash (deterministic, lexical, dependency-free, offline). Set MEMORYLAYER_EMBEDDING_PROVIDER=embed_server to use the peer, reached via MEMORYLAYER_EMBED_SERVER_URL (default http://localhost:61051).

Removed in v0.1.x: the in-process local (sentence-transformers), colpali, and qwen3-vl providers and their extras ([local], [colpali], [qwen3-vl]) were removed from memorylayer-server. Heavy ML now lives in memorylayer-embed-server. Setting the legacy provider names raises a startup error with migration guidance.

Start the Server

Terminal window
# HTTP server (default port 61001)
memorylayer serve


# Custom port
memorylayer serve --port 8080


# Debug mode
memorylayer serve --verbose

Verify Installation

Terminal window
curl http://localhost:61001/health

You should see a JSON response confirming the server is running.

Docker

Run the server as a Docker container:

Terminal window
# Cloud embeddings via OpenAI (recommended quick start for the container)
docker run -d \
  --name memorylayer \
  -p 61001:61001 \
  -v memorylayer-data:/data \
  -e MEMORYLAYER_EMBEDDING_PROVIDER=openai \
  -e MEMORYLAYER_EMBEDDING_OPENAI_API_KEY=sk-... \
  scitrera/memorylayer-server


# Cloud embeddings via Google GenAI
docker run -d \
  --name memorylayer \
  -p 61001:61001 \
  -v memorylayer-data:/data \
  -e MEMORYLAYER_EMBEDDING_PROVIDER=google \
  -e MEMORYLAYER_EMBEDDING_GOOGLE_API_KEY=... \
  scitrera/memorylayer-server


# Self-hosted: pair with a memorylayer-embed-server peer
docker run -d \
  --name memorylayer \
  -p 61001:61001 \
  -v memorylayer-data:/data \
  -e MEMORYLAYER_EMBEDDING_PROVIDER=embed_server \
  -e MEMORYLAYER_EMBED_SERVER_URL=http://embed-host:61051 \
  scitrera/memorylayer-server


# Local smoke test (no external dependencies; deterministic lexical vectors)
docker run -d \
  --name memorylayer \
  -p 61001:61001 \
  -v memorylayer-data:/data \
  -e MEMORYLAYER_EMBEDDING_PROVIDER=hash \
  scitrera/memorylayer-server

The container installs the core server with cloud-embedding and document-parser extras, and pre-sets MEMORYLAYER_EMBEDDING_PROVIDER=embed_server — so a bare docker run expects a memorylayer-embed-server peer and fails loudly if it cannot reach one. That is deliberate: a missing peer is a startup error rather than a silent downgrade to lexical matching. Override the variable, as in the examples above, to use openai, google, or hash instead. Data is persisted in the /data volume. See the Configuration page for all available environment variables.

hash vs mock: hash is the server’s default — a dependency-free lexical provider where texts sharing words get a meaningful similarity, so retrieval returns sensible rankings offline. mock hashes each string into an essentially random vector and carries no token-level signal; use it only for wiring tests, never to evaluate recall quality.

Client SDKs

Python SDK

Terminal window
pip install memorylayer-client
from memorylayer import MemoryLayerClient


async with MemoryLayerClient(
    base_url="http://localhost:61001",
    workspace_id="my-workspace"
) as client:
    memory = await client.remember("Hello, MemoryLayer!")

TypeScript SDK

Terminal window
npm install @scitrera/memorylayer-sdk
import { MemoryLayerClient } from "@scitrera/memorylayer-sdk";


const client = new MemoryLayerClient({
  baseUrl: "http://localhost:61001",
  workspaceId: "my-workspace",
});


const memory = await client.remember("Hello, MemoryLayer!");

Framework Integrations

MCP Server (Claude Code / Claude Desktop)

Terminal window
npm install @scitrera/memorylayer-mcp-server

See MCP Server Integration for setup instructions.

LangChain

Terminal window
pip install memorylayer-langchain

See LangChain Integration for usage guide.

LlamaIndex

Terminal window
pip install memorylayer-llamaindex

See LlamaIndex Integration for usage guide.

System Requirements

  • Server: Python 3.12+
  • Python SDK: Python 3.12+
  • TypeScript SDK: Node.js 18+
  • MCP Server: Node.js 18+

Development Installation

For contributing to MemoryLayer, clone the repository and install in development mode:

Terminal window
git clone https://github.com/scitrera/memorylayer
cd memorylayer
python -m venv .venv && source .venv/bin/activate


# Server
pip install -e "memorylayer-core-python[dev]"


# Python SDK
pip install -e "memorylayer-sdk-python[dev]"


# TypeScript SDK
cd memorylayer-sdk-typescript
npm install
npm run build