memorylayer-core-python

MemoryLayer.ai Server

API-first memory infrastructure for LLM-powered agents.

MemoryLayer provides cognitive memory capabilities for AI agents, including episodic, semantic, procedural, and working memory with vector-based retrieval, graph-based associations, and server-side computation sandboxes.

Features

• Cognitive Memory Architecture — Episodic, semantic, procedural, and working memory types
• Vector Search — SQLite with sqlite-vec for efficient similarity search
• Knowledge Graph — 60+ relationship types organized into 11 categories for memory associations
• Context Environment — Server-side Python sandboxes for memory analysis and computation
• Session Management — Working memory with TTL and commit to long-term storage
• REST API — Full-featured HTTP API for all memory operations
• Multiple Embedding Providers — OpenAI, Google GenAI, embed-server (self-hosted GPU via memorylayer-embed-server), and mock (testing)
• Health Endpoints — /health and /health/ready for monitoring and readiness checks

Installation

# Basic installation
pip install memorylayer-server
# With OpenAI embeddings
pip install memorylayer-server[openai]
# With Google GenAI embeddings
pip install memorylayer-server[google]
# Self-hosted embeddings: install + run memorylayer-embed-server separately# (no extras here — the main server only speaks HTTP to embed-server)# pip install memorylayer-embed-server[gpu]# All cloud embedding providers + LLM + document parsers
pip install memorylayer-server[all]

Package name:memorylayer-server (PyPI) Import name:memorylayer_server

Quick Start

Start the HTTP Server

# Start on default port (61001)
memorylayer serve
# Custom port
memorylayer serve --port 8080
# Bind to all interfaces
memorylayer serve --host 0.0.0.0
# Debug mode
memorylayer serve --verbose

Docker

The official Docker image comes with all optional dependencies pre-installed. The default embedding provider is embed_server, which delegates all GPU/ML work to a peer memorylayer-embed-server container — set MEMORYLAYER_EMBED_SERVER_URL accordingly, or override the provider entirely (mock for tests, openai/google for cloud):

docker run -d \
--name memorylayer \
-p 61001:61001 \
-v memorylayer-data:/data \
scitrera/memorylayer-server

With OpenAI embeddings:

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

API Usage

The server exposes a REST API. Use any HTTP client, or install the Python SDK (pip install memorylayer-client) for a typed client:

frommemorylayerimportMemoryLayerClientasyncwithMemoryLayerClient(base_url="http://localhost:61001") asclient:
# Store a memorymemory=awaitclient.remember(
content="User prefers Python for backend development",
type="semantic",
importance=0.8,
tags=["preferences", "programming"]
)
# Recall memoriesresults=awaitclient.recall(
query="What programming languages does the user like?",
limit=5
)
# Create associationsawaitclient.associate(
source_id=memory.id,
target_id=other_memory.id,
relationship="related_to",
strength=0.9
)

Configuration

Environment Variables

Variable	Default	Description
MEMORYLAYER_SERVER_HOST	127.0.0.1	Server bind address
MEMORYLAYER_SERVER_PORT	61001	Server port
MEMORYLAYER_DATA_DIR	~/.config/memorylayer-server	Data directory
MEMORYLAYER_SQLITE_STORAGE_PATH	memorylayer.db	SQLite database path (relative to data dir)
MEMORYLAYER_EMBEDDING_PROVIDER	embed_server	Embedding provider (openai, google, embed_server, mock)
MEMORYLAYER_EMBEDDING_OPENAI_API_KEY	—	OpenAI API key
MEMORYLAYER_EMBEDDING_GOOGLE_API_KEY	—	Google API key
MEMORYLAYER_EMBED_SERVER_URL	http://localhost:61051	Base URL for memorylayer-embed-server (used by embed_server provider)
MEMORYLAYER_EMBED_TRANSPORT	http	http for direct calls or aether for cross-DC mTLS via Aether

Embedding Providers

The legacy in-process providers local (sentence-transformers), colpali (colpali-engine), and qwen3-vl (qwen-vl-utils) were removed. All self-hosted/multi-vector embedding now routes through the embed_server provider, which delegates to the standalone memorylayer-embed-server package. Setting any of those legacy values for MEMORYLAYER_EMBEDDING_PROVIDER raises a startup error with migration guidance.

Embed-server (self-hosted, default) — Run memorylayer-embed-server as a peer process or container; the main server only speaks HTTP to it:

# In a GPU-equipped peer:
pip install memorylayer-embed-server[gpu]
memorylayer-embed-server serve --port 61051
# In the main server process:export MEMORYLAYER_EMBEDDING_PROVIDER=embed_server
export MEMORYLAYER_EMBED_SERVER_URL=http://embed-host:61051
memorylayer serve

OpenAI:

pip install memorylayer-server[openai]
export MEMORYLAYER_EMBEDDING_PROVIDER=openai
export MEMORYLAYER_EMBEDDING_OPENAI_API_KEY=sk-...
memorylayer serve

Google GenAI:

pip install memorylayer-server[google]
export MEMORYLAYER_EMBEDDING_PROVIDER=google
export MEMORYLAYER_EMBEDDING_GOOGLE_API_KEY=...
memorylayer serve

Mock (testing only):

export MEMORYLAYER_EMBEDDING_PROVIDER=mock
memorylayer serve

LLM Provider (Optional)

Some features (reflection, smart extraction, context environment queries) require an LLM provider configured via profiles:

# OpenAIexport MEMORYLAYER_LLM_PROFILE_DEFAULT_PROVIDER=openai
export MEMORYLAYER_LLM_PROFILE_DEFAULT_API_KEY=sk-...
# Anthropic Claudeexport MEMORYLAYER_LLM_PROFILE_DEFAULT_PROVIDER=anthropic
export MEMORYLAYER_LLM_PROFILE_DEFAULT_API_KEY=sk-ant-...
# Google Geminiexport MEMORYLAYER_LLM_PROFILE_DEFAULT_PROVIDER=google
export MEMORYLAYER_LLM_PROFILE_DEFAULT_API_KEY=...

Profile configuration variables (replace DEFAULT with any profile name):

Variable	Description
MEMORYLAYER_LLM_PROFILE_<NAME>_PROVIDER	Provider (openai, anthropic, google)
MEMORYLAYER_LLM_PROFILE_<NAME>_API_KEY	API key
MEMORYLAYER_LLM_PROFILE_<NAME>_MODEL	Model name override
MEMORYLAYER_LLM_PROFILE_<NAME>_BASE_URL	Custom API base URL
MEMORYLAYER_LLM_PROFILE_<NAME>_MAX_TOKENS	Max response tokens
MEMORYLAYER_LLM_PROFILE_<NAME>_TEMPERATURE	Sampling temperature

Without an LLM provider, core memory operations (remember, recall, forget, associate) work normally, but synthesis features will be unavailable.

Context Environment

The Context Environment provides server-side Python sandboxes for memory analysis and computation. See Context Environment documentation for details.

Configuration:

Variable	Default	Description
MEMORYLAYER_CONTEXT_EXECUTOR	smolagents	Executor backend (smolagents or restricted)
MEMORYLAYER_CONTEXT_MAX_EXEC_SECONDS	30	Timeout per code execution
MEMORYLAYER_CONTEXT_MAX_OUTPUT_CHARS	50000	Max captured stdout characters
MEMORYLAYER_CONTEXT_QUERY_MAX_TOKENS	4096	Max tokens for server-side LLM queries
MEMORYLAYER_CONTEXT_MAX_MEMORY_BYTES	268435456	Memory limit per sandbox (256 MB)
MEMORYLAYER_CONTEXT_RLM_MAX_ITERATIONS	10	Max iterations for RLM loops
MEMORYLAYER_CONTEXT_RLM_MAX_EXEC_SECONDS	120	Total timeout for RLM loops
MEMORYLAYER_CONTEXT_MAX_OPERATIONS	1000000	Max operations per sandbox execution

Storage

The default storage backend is SQLite with sqlite-vec for vector operations. The database file defaults to ~/.config/memorylayer-server/memorylayer.db and contains all memories, embeddings, associations, and session data.

Override the data directory:

export MEMORYLAYER_DATA_DIR=/var/lib/memorylayer

Override the database path:

export MEMORYLAYER_SQLITE_STORAGE_PATH=/var/lib/memorylayer/data.db

Recall Modes

The active recall mode is RAG (vector similarity + graph traversal). LLM and Hybrid modes are deprecated.

MCP Integration

The Model Context Protocol (MCP) server is a separate TypeScript package (@scitrera/memorylayer-mcp-server), not part of this Python server CLI.

To use MemoryLayer with Claude Code or Claude Desktop:

1. Start the HTTP server: memorylayer serve
2. Install and configure the MCP server: npm install -g @scitrera/memorylayer-mcp-server

See the MCP Server documentation for setup instructions.

Health Checks

• GET /health — Basic health check (returns immediately)
• GET /health/ready — Readiness check (verifies storage connectivity)

The Docker image includes a built-in health check at /health (every 30s, 10s startup grace period).

Documentation

• Website:https://memorylayer.ai
• Docs:https://docs.memorylayer.ai
• GitHub:https://github.com/scitrera/memorylayer

License

Apache 2.0 License -- see LICENSE for details.