Getting Started

This guide will walk you through deploying Memory Service using Docker Compose for a quick demo setup.

Note: This project is currently in the proof-of-concept (POC) phase and has not yet published any releases. To try it out, you’ll need to build it from source code. Don’t worry—Docker Compose will handle building the project automatically when you run the deployment commands below. Be aware that the initial build may take several minutes, so please be patient.

Prerequisites

Before you begin, make sure you have:

Docker and Docker Compose installed
An OpenAI API key (or compatible endpoint)

Quick Start

1. Clone the Repository

git clone https://github.com/chirino/memory-service.git
cd memory-service

2. Set Up Environment

Create a .env file with your OpenAI API key:

echo "OPENAI_API_KEY=your-api-key-here" > .env

3. Deploy with Docker Compose

docker compose build
docker compose up -d

This will start:

Demo Chat App for an AI chat interface
Memory Service this project’s service (used by the demo chat app)
Keycloak for authentication (used by the memory service and demo chat app)
PostgreSQL for data and vector storage (used by the memory service)
Redis for caching (used by the memory service)
Qdrant for vector search (used by the memory service)
Infinispan for caching and vector search (used by the memory service)
MinIO for S3-compatible object storage (used by the memory service for attachments)
Prometheus for metrics collection
Grafana for metrics dashboards

Optional Services

Langfuse Observability

Enable turn-trace observability and LLM monitoring with Langfuse:

docker compose --profile langfuse up -d

Langfuse is available at http://localhost:3002 with:

Email: memory-service@example.com
Password: memory-service

Cognition Processor

Enable intelligent memory extraction and organization using LLMs:

docker compose --profile cognition up -d

The cognition processor extracts structured memories (facts, preferences, topics) from conversations. Configure it by adding these variables to your .env file:

Variable	Description	Default
`COGNITION_OPENAI_API_KEY`	API key for the LLM endpoint	(required)
`COGNITION_OPENAI_BASE_URL`	OpenAI-compatible LLM endpoint	`https://api.openai.com/v1`
`COGNITION_OPENAI_MODEL_NAME`	Model name for extraction/verification	`gpt-4o`

Minimum configuration (using defaults):

COGNITION_OPENAI_API_KEY=your-api-key-here

Custom endpoint and model:

COGNITION_OPENAI_API_KEY=your-api-key-here
COGNITION_OPENAI_BASE_URL=https://api.openai.com/v1
COGNITION_OPENAI_MODEL_NAME=gpt-4o

Learn more about the cognition layer in the Memory Cognition documentation.

4. Access the Demo Chat App

Open http://localhost:8080 in your browser and sign in with:

Username: bob
Password: bob

Test Users

Keycloak is pre-configured with these test users:

Username	Password	Role
bob	bob	user
alice	alice	user, admin
charlie	charlie	user

Things to notice in the Demo.

You can fork any user entry and switch between forks
Agent memory stays consistent with the fork you’re on. Ask it to recall previous fact you have told it.
Streaming responses survive browser page reloads. You can even switch to a different device and still view the response that is currently being generated.
Users can see a list of all their previous conversations.

Next Steps

Understand the APIs exposed by the Memory Service in Core Concepts
Explore Developer Guides for
Learn how to configure the service