> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aegismemory.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> Get secure agent context running in 2 minutes

# Installation

This guide walks you through installing the Aegis Memory SDK and starting the memory server locally.

## Prerequisites

Before you begin, ensure you have:

* **Python 3.9+** — Check with `python --version`
* **Docker & Docker Compose** — The memory server runs in containers
* **OpenAI API key** — Used for generating embeddings ([get one here](https://platform.openai.com/api-keys))

## Step 1: Install the SDK

```bash theme={null}
pip install aegis-memory
```

With framework integrations:

```bash theme={null}
# For CrewAI
pip install "aegis-memory[crewai]"

# For LangChain
pip install "aegis-memory[langchain]"

# All integrations
pip install "aegis-memory[all]"
```

## Step 2: Start the Memory Server

<Tabs>
  <Tab title="Quick Start (Recommended)">
    ```bash theme={null}
    aegis quickstart
    ```

    This command:

    * Downloads the Docker Compose configuration
    * Starts PostgreSQL with pgvector
    * Starts the Aegis API server
    * Runs health checks
  </Tab>

  <Tab title="Manual Setup">
    Clone and start manually:

    ```bash theme={null}
    git clone https://github.com/quantifylabs/aegis-memory.git
    cd aegis-memory
    docker-compose up -d
    ```

    Verify it's running:

    ```bash theme={null}
    curl http://localhost:8000/health
    ```
  </Tab>
</Tabs>

## Step 3: Configure Environment

Create a `.env` file in your project directory:

```bash .env theme={null}
# Required for embeddings
OPENAI_API_KEY=sk-your-openai-key-here

# For local development, any string works as the API key
AEGIS_API_KEY=dev-key

# Optional: defaults to localhost
AEGIS_BASE_URL=http://localhost:8000
```

Or export them directly in your terminal:

```bash theme={null}
export OPENAI_API_KEY="sk-..."
export AEGIS_API_KEY="dev-key"
```

## Step 4: Verify Installation

```python theme={null}
from aegis_memory import AegisClient

client = AegisClient(
    api_key="dev-key",
    base_url="http://localhost:8000"
)

# Add a test memory
result = client.add("Test memory - Aegis is working!")
print(f"Memory stored: {result.id}")

# Query it back
memories = client.query("test memory")
print(f"Retrieved: {memories[0].content}")
```

<Check>You should see your test memory returned! If so, Aegis is ready to use.</Check>

## Next Steps

<CardGroup cols={2}>
  <Card title="First Memory" icon="brain" href="/quickstart/first-memory">
    Store and retrieve your first real memory
  </Card>

  <Card title="CrewAI Integration" icon="users" href="/quickstart/with-crewai">
    Add memory to CrewAI agents
  </Card>
</CardGroup>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Docker containers won't start">
    Check if ports 8000 or 5432 are already in use:

    ```bash theme={null}
    lsof -i :8000
    lsof -i :5432
    ```

    Kill conflicting processes or change ports in `docker-compose.yml`.
  </Accordion>

  <Accordion title="Connection refused errors">
    Wait for PostgreSQL to be ready:

    ```bash theme={null}
    docker-compose logs postgres
    ```

    Look for "database system is ready to accept connections".
  </Accordion>

  <Accordion title="OpenAI API errors">
    Ensure your API key is set and has credits:

    ```bash theme={null}
    echo $OPENAI_API_KEY
    ```

    Test directly:

    ```bash theme={null}
    curl https://api.openai.com/v1/models \
      -H "Authorization: Bearer $OPENAI_API_KEY"
    ```
  </Accordion>
</AccordionGroup>

***

## Reference: What's Running

After starting the server, these services are available:

| Service          | Port | Purpose                        |
| ---------------- | ---- | ------------------------------ |
| Aegis API        | 8000 | REST API for memory operations |
| PostgreSQL       | 5432 | Vector storage with pgvector   |
| Redis (optional) | 6379 | Caching and rate limiting      |