Overview

Relevant source files

• LICENSE
• README.md
• assets/img/MemMachine_Hero_Banner.png
• maintainers/build-pip-packages.md
• packages/client/pyproject.toml
• packages/meta/README.md
• packages/server/pyproject.toml
• pyproject.toml
• uv.lock

This document provides a high-level introduction to MemMachine, covering its purpose, architecture, and key components. For detailed information on specific subsystems, refer to the linked sections throughout this page.

What is MemMachine

MemMachine is an open-source memory system for AI agents that provides persistent storage and retrieval of conversational context and user information. It implements two memory types: episodic memory (conversation history) and semantic memory (structured user profiles).

Core Features:

• Episodic Memory: Graph-based storage of conversation history with vector search capabilities
• Semantic Memory: Structured user profiles with LLM-based feature extraction
• Project Isolation: Multi-tenant architecture with org_id/project_id namespacing
• Multiple Protocols: REST API v2, Python SDK, and Model Context Protocol (MCP) support
• LLM Provider Agnostic: Supports OpenAI, AWS Bedrock, Ollama, and OpenAI-compatible APIs

MemMachine operates as a standalone service that AI agents and applications integrate with via client libraries or HTTP APIs. The system manages memory persistence across sessions, deployments, and agent restarts.

Sources: README.md26-36 packages/server/pyproject.toml6-51 packages/client/pyproject.toml6-31

System Architecture

MemMachine implements a three-tier architecture: client libraries communicate with API servers, which orchestrate memory operations across PostgreSQL and Neo4j databases.

Deployment Architecture

Architecture Layers:

Layer	Purpose	Key Components
Client	Application integration	memmachine-client package, REST clients, MCP clients
API	Protocol handling	api_v2.router, mcp_stdio.py, mcp_http.py
Core	Memory orchestration	MemMachine, EpisodicMemoryManager, ProfileMemory
Storage	Data persistence	PostgreSQL (profiles), Neo4j (episodes), SQLite (dev)

Sources: packages/server/src/memmachine/server/app.py1-20 packages/server/pyproject.toml58-63 README.md135-137

Monorepo Structure

MemMachine uses a uv workspace monorepo with three packages: memmachine-common (shared code), memmachine-server (server application), and memmachine-client (REST client library).

Package Organization

Package Responsibilities:

Package	Purpose	Python Version	Key Contents
memmachine-common	Shared schemas and models	>= 3.12	Pydantic API models, data structures
memmachine-server	Server application	>= 3.12	FastAPI server, memory systems, MCP servers
memmachine-client	Client library	>= 3.10	REST client, type-safe API wrappers
memmachine (meta)	Convenience installer	N/A	Empty package, installs client + server

Sources: uv.lock1-10 pyproject.toml1-19 packages/server/pyproject.toml1-51 packages/client/pyproject.toml1-53 packages/meta/README.md1-15

Core Components

The following table summarizes the primary components in MemMachine and links to their detailed documentation:

Component	Purpose	See Section
Memory Types	Episodic (short-term/long-term) and semantic (profile) memory	#3.3, #3.4, #3.5
Projects & Sessions	Namespace isolation and multi-tenancy	#3.6
Client SDK	Python library for interacting with MemMachine	#4.4
REST API v2	HTTP/JSON API for all operations	#4.2
MCP Server	Model Context Protocol implementation	#4.3
Embedders	Text-to-vector conversion for semantic search	#3.7.1
Language Models	LLM integration for feature extraction	#3.7.2
Rerankers	Result ranking using BM25, RRF, cross-encoder	#3.7.3
Storage Layer	PostgreSQL, Neo4j, SQLite backends	#3.8
Configuration	configuration.yml and environment variables	#7

Sources: Table of contents from provided JSON structure

Memory System Overview

MemMachine implements two memory types: Episodic Memory stores conversation history as a graph, while Semantic Memory extracts and maintains structured user profiles.

Memory Types:

Memory Type	Storage	Primary Use Case	Key Classes
Episodic	Neo4j graph (long-term) PostgreSQL (short-term)	Conversational context retrieval	EpisodicMemory, ShortTermMemory, LongTermMemory
Semantic	PostgreSQL prof table	Structured user facts and preferences	ProfileMemory, ProfileStorage

How Memory Types Work Together:

1. Episodic memory records raw conversational turns and enables semantic search across conversation history
2. Semantic memory extracts structured facts from episodes using LLMs and stores them with citations back to source episodes
3. Both memory types can be queried independently or together via the API

For detailed architecture of each memory type, see sections 4.2 (Episodic Memory System) and 4.3 (Semantic Memory System).

Sources: packages/server/pyproject.toml58-63 README.md32-35

API Surface

MemMachine provides three integration interfaces: REST API v2 for HTTP clients, Python SDK for application integration, and MCP servers for AI IDE tools.

Available Interfaces:

Interface	Package/Module	Use Case	Transport
REST API v2	memmachine.server.api_v2.router	HTTP clients, web apps, curl	HTTP/JSON on port 8080
Python SDK	memmachine-client package	Python applications, agents	Python API → HTTP
MCP STDIO	memmachine-mcp-stdio command	Claude Desktop, Cursor	stdin/stdout JSON-RPC
MCP HTTP	memmachine-mcp-http command	Remote MCP clients	HTTP JSON-RPC

Python Client Example:

REST API Key Endpoints:

• POST /api/v2/projects - Create project
• POST /api/v2/memories - Add memories
• POST /api/v2/memories/search - Search memories
• GET /health - Health check
• GET /metrics - Prometheus metrics

For complete API documentation, see section 6 (API Reference).

Sources: packages/server/pyproject.toml58-63 packages/client/pyproject.toml1-53 README.md44-73

Technology Stack

MemMachine is implemented in Python 3.12+ and uses the following core dependencies:

Component	Technology	Purpose
Web Framework	FastAPI + Uvicorn	Async HTTP server and REST API
Databases	PostgreSQL + pgvector, Neo4j, SQLite	Vector search, graph storage, development
Database Drivers	asyncpg, neo4j, aiosqlite	Async database connectivity
ORM & Migrations	SQLAlchemy, Alembic	Database abstraction and schema management
LLM Integration	openai, boto3, instructor	OpenAI, AWS Bedrock, structured outputs
Vector & Reranking	pgvector, rank-bm25, cohere	Similarity search and result ranking
MCP Protocol	fastmcp	Model Context Protocol server
Data Validation	pydantic	Request/response schemas
Package Manager	uv	Monorepo and dependency management

Python Version Requirements:

• Server (memmachine-server): Python >= 3.12
• Client (memmachine-client): Python >= 3.10

Sources: packages/server/pyproject.toml8-36 packages/client/pyproject.toml8-14 uv.lock1-10

Configuration

MemMachine configuration uses environment variables for infrastructure settings and configuration.yml for AI service providers.

Configuration Sources:

1. Environment Variables - Database URLs, API keys, server ports
2. configuration.yml - LLM providers, embedders, rerankers, memory settings

Configuration Helper:

For detailed configuration reference, see section 5 (Configuration Reference).

Sources: packages/server/pyproject.toml58-63 README.md39-42

Installation Methods

MemMachine can be installed via Docker Compose, pip packages, or from source.

Installation Options:

Method	Command	Best For
Docker Compose	./memmachine-compose.sh	Quick start, includes all dependencies
pip (server)	pip install memmachine-server	Custom server deployments
pip (client)	pip install memmachine-client	Client-only integration
pip (full)	pip install memmachine	Install both client and server

Quick Start with Docker Compose:

For detailed installation guides, see section 2 (Getting Started).

Sources: README.md37-76 maintainers/build-pip-packages.md1-171

Projects and Multi-Tenancy

MemMachine uses project-based isolation with org_id and project_id identifiers. Each project maintains separate memory instances and database namespaces.

Isolation Model:

• Project: Defined by org_id/project_id pair, creates set_id for database isolation
• Session: Defined by user_id, agent_id, session_id within a project
• Database Filtering: All queries filter by set_id to enforce isolation

Project Context Structure:

Database tables use set_id to enforce isolation: all queries include WHERE set_id = ? clauses to prevent cross-project data access.

For detailed project and session management, see section 4.4 (Projects and Session Management).

Sources: README.md54-62 packages/server/pyproject.toml1-91

Getting Started

The quickest way to run MemMachine locally is using the Docker Compose setup script:

What the Setup Script Provides:

• Interactive configuration wizard for AI providers (OpenAI, AWS Bedrock, Ollama)
• Automatic generation of configuration.yml and .env files
• Docker Compose orchestration of PostgreSQL, Neo4j, and MemMachine server
• Health checks to verify all services are operational

Basic Python Usage:

For detailed setup guides, see section 2 (Getting Started). For API examples, see section 6 (API Reference).

Sources: README.md37-76 README.md44-73

Next Steps

Topic	Section
Core architecture and memory types	#3
API reference and SDK documentation	#4
Integration with AI frameworks	#5
Usage examples and patterns	#6
Configuration reference	#7
Production deployment	#8
Development and contribution	#9

Sources: Table of contents from provided JSON structure