> ## Documentation Index
> Fetch the complete documentation index at: https://crewai.burt.pe.kr/llms.txt
> Use this file to discover all available pages before exploring further.

# Memory

> CrewAI 프레임워크에서 메모리 시스템을 활용해 에이전트의 능력을 강화하는 방법

## CrewAI의 메모리 시스템 소개

crewAI 프레임워크는 AI 에이전트의 능력을 크게 향상시키기 위해 설계된 정교한 메모리 시스템을 도입한다. 이 시스템은 `단기 메모리`, `장기 메모리`, `엔티티 메모리`, `컨텍스트 메모리`로 구성되며, 각각 에이전트가 과거 상호작용을 기억하고, 추론하고, 학습하는 데 독특한 목적을 제공한다.

## 메모리 시스템 구성 요소

| 구성 요소        | 설명                                                                                          |
| :----------- | :------------------------------------------------------------------------------------------ |
| **단기 메모리**   | `RAG`를 사용해 최근 상호작용과 결과를 임시로 저장한다. 에이전트가 현재 실행 중에 관련 정보를 기억하고 활용할 수 있게 한다.                   |
| **장기 메모리**   | 과거 실행에서 얻은 유용한 통찰과 학습 내용을 보존한다. 에이전트가 시간이 지남에 따라 지식을 구축하고 정교화할 수 있게 한다.                     |
| **엔티티 메모리**  | 작업 중 마주친 엔티티(사람, 장소, 개념)에 대한 정보를 캡처하고 조직화한다. 더 깊은 이해와 관계 매핑을 지원한다. `RAG`를 사용해 엔티티 정보를 저장한다. |
| **컨텍스트 메모리** | `단기 메모리`, `장기 메모리`, `엔티티 메모리`를 결합해 상호작용의 컨텍스트를 유지한다. 일련의 작업이나 대화에서 에이전트 응답의 일관성과 관련성을 높인다.  |
| **사용자 메모리**  | 사용자별 정보와 선호도를 저장한다. 개인화와 사용자 경험을 향상시킨다.                                                     |

## 메모리 시스템이 에이전트에 힘을 실어주는 방식

1. **상황 인식**: 단기 및 상황 메모리를 통해 에이전트는 대화나 작업 시퀀스 동안 상황을 유지할 수 있다. 이로 인해 더 일관적이고 관련성 높은 응답을 제공한다.

2. **경험 축적**: 장기 메모리는 에이전트가 경험을 축적할 수 있게 한다. 과거의 행동을 통해 배우고, 미래의 결정과 문제 해결 능력을 향상시킨다.

3. **엔티티 이해**: 엔티티 메모리를 유지함으로써 에이전트는 주요 엔티티를 인식하고 기억할 수 있다. 이를 통해 복잡한 정보를 처리하고 상호작용하는 능력이 향상된다.

## 크루에 메모리 기능 구현하기

크루를 구성할 때, 각 메모리 컴포넌트를 활성화하고 크루의 목적과 수행할 작업의 특성에 맞게 커스텀할 수 있다. 기본적으로 메모리 시스템은 비활성화되어 있으며, 크루 설정에서 `memory=True`로 설정해 활성화할 수 있다. 메모리는 기본적으로 OpenAI 임베딩을 사용하지만, `embedder`를 다른 모델로 설정해 변경할 수 있다. 또한, 직접 생성한 메모리 인스턴스로 초기화할 수도 있다.

'embedder'는 **단기 메모리**에만 적용되며, 단기 메모리는 RAG를 위해 Chroma를 사용한다. **장기 메모리**는 작업 결과를 저장하기 위해 SQLite3을 사용한다. 현재는 이러한 스토리지 구현을 재정의할 수 있는 방법이 없다. 데이터 스토리지 파일은 appdirs 패키지를 통해 플랫폼별 특정 위치에 저장되며, **CREWAI\_STORAGE\_DIR** 환경 변수를 사용해 프로젝트 이름을 재정의할 수 있다.

### 예제: Crew를 위한 메모리 설정

```python theme={null}
from crewai import Crew, Agent, Task, Process

# 메모리 기능을 갖춘 Crew를 조립한다
my_crew = Crew(
    agents=[...],
    tasks=[...],
    process=Process.sequential,
    memory=True,
    verbose=True
)
```

### 예제: FAISS와 같은 커스텀 메모리 인스턴스를 VectorDB로 사용하기

```python theme={null}
from crewai import Crew, Process
from crewai.memory import LongTermMemory, ShortTermMemory, EntityMemory
from crewai.memory.storage import LTMSQLiteStorage, RAGStorage
from typing import List, Optional

# 메모리 기능을 갖춘 크루를 조립한다
my_crew: Crew = Crew(
    agents = [...],
    tasks = [...],
    process = Process.sequential,
    memory = True,
    # 세션 간 지속적인 저장을 위한 장기 메모리
    long_term_memory = LongTermMemory(
        storage=LTMSQLiteStorage(
            db_path="/my_crew1/long_term_memory_storage.db"
        )
    ),
    # RAG를 사용한 현재 컨텍스트를 위한 단기 메모리
    short_term_memory = ShortTermMemory(
        storage = RAGStorage(
                embedder_config={
                    "provider": "openai",
                    "config": {
                        "model": 'text-embedding-3-small'
                    }
                },
                type="short_term",
                path="/my_crew1/"
            )
        ),
    ),
    # 엔티티에 대한 주요 정보를 추적하기 위한 엔티티 메모리
    entity_memory = EntityMemory(
        storage=RAGStorage(
            embedder_config={
                "provider": "openai",
                "config": {
                    "model": 'text-embedding-3-small'
                }
            },
            type="short_term",
            path="/my_crew1/"
        )
    ),
    verbose=True,
)
```

## 보안 고려 사항

메모리 저장소를 설정할 때 다음 사항을 고려한다:

* 저장소 경로에는 환경 변수를 사용한다 (예: `CREWAI_STORAGE_DIR`)
* 데이터베이스 자격 증명과 같은 민감한 정보를 하드코딩하지 않는다
* 저장소 디렉터리의 접근 권한을 신중히 설정한다
* 이식성을 유지하기 위해 가능한 경우 상대 경로를 사용한다

환경 변수를 사용한 예제:

```python theme={null}
import os
from crewai import Crew
from crewai.memory import LongTermMemory
from crewai.memory.storage import LTMSQLiteStorage

# 환경 변수를 사용해 저장소 경로 설정
storage_path = os.getenv("CREWAI_STORAGE_DIR", "./storage")
crew = Crew(
    memory=True,
    long_term_memory=LongTermMemory(
        storage=LTMSQLiteStorage(
            db_path="{storage_path}/memory.db".format(storage_path=storage_path)
        )
    )
)
```

## 설정 예제

### 기본 메모리 설정

```python theme={null}
from crewai import Crew
from crewai.memory import LongTermMemory

# 간단한 메모리 설정
crew = Crew(memory=True)  # 기본 저장 위치 사용
```

### 커스텀 스토리지 설정

```python theme={null}
from crewai import Crew
from crewai.memory import LongTermMemory
from crewai.memory.storage import LTMSQLiteStorage

# 커스텀 스토리지 경로 설정
crew = Crew(
    memory=True,
    long_term_memory=LongTermMemory(
        storage=LTMSQLiteStorage(db_path="./memory.db")
    )
)
```

## 사용자 메모리 향상을 위한 Mem0 통합

[Mem0](https://mem0.ai/)는 LLM 애플리케이션을 위한 자기 개선형 메모리 레이어로, 개인화된 AI 경험을 가능하게 한다.

사용자별 메모리를 포함하려면 [여기](https://app.mem0.ai/dashboard/api-keys)에서 API 키를 얻고 [문서](https://docs.mem0.ai/platform/quickstart#4-1-create-memories)를 참조해 사용자 선호도를 추가할 수 있다.

```python theme={null}
import os
from crewai import Crew, Process
from mem0 import MemoryClient

# Mem0 환경 변수 설정
os.environ["MEM0_API_KEY"] = "m0-xx"

# 1단계: 과거 대화나 사용자 입력을 기반으로 선호도 기록
client = MemoryClient()
messages = [
    {"role": "user", "content": "안녕하세요! 휴가 계획을 세우고 있는데 조언이 필요합니다."},
    {"role": "assistant", "content": "안녕하세요! 휴가 계획을 도와드릴게요. 어떤 종류의 여행지를 선호하시나요?"},
    {"role": "user", "content": "저는 산보다 해변을 더 좋아해요."},
    {"role": "assistant", "content": "흥미롭네요. 호텔과 Airbnb 중 어떤 것을 선호하시나요?"},
    {"role": "user", "content": "저는 Airbnb를 더 좋아해요."},
]
client.add(messages, user_id="john")

# 2단계: 사용자 메모리를 포함한 Crew 생성

crew = Crew(
    agents=[...],
    tasks=[...],
    verbose=True,
    process=Process.sequential,
    memory=True,
    memory_config={
        "provider": "mem0",
        "config": {"user_id": "john"},
    },
)
```

## 메모리 설정 옵션

특정 조직과 프로젝트에 접근하려면 메모리 설정에서 `org_id`와 `project_id` 파라미터를 설정할 수 있다.

```python theme={null}
from crewai import Crew

crew = Crew(
    agents=[...],
    tasks=[...],
    verbose=True,
    memory=True,
    memory_config={
        "provider": "mem0",
        "config": {"user_id": "john", "org_id": "my_org_id", "project_id": "my_project_id"},
    },
)
```

## 추가 임베딩 프로바이더 사용

### OpenAI 임베딩 사용 (기본 설정)

```python theme={null}
from crewai import Crew, Agent, Task, Process

my_crew = Crew(
    agents=[...],
    tasks=[...],
    process=Process.sequential,
    memory=True,
    verbose=True,
    embedder={
        "provider": "openai",
        "config": {
            "model": 'text-embedding-3-small'
        }
    }
)
```

또는 OpenAIEmbeddingFunction을 embedder 인자에 직접 전달할 수 있다.

예시:

```python theme={null}
from crewai import Crew, Agent, Task, Process
from chromadb.utils.embedding_functions import OpenAIEmbeddingFunction

my_crew = Crew(
    agents=[...],
    tasks=[...],
    process=Process.sequential,
    memory=True,
    verbose=True,
    embedder={
        "provider": "openai",
        "config": {
            "model": 'text-embedding-3-small'
        }
    }
)
```

### Ollama 임베딩 사용하기

```python theme={null}
from crewai import Crew, Agent, Task, Process

my_crew = Crew(
    agents=[...],
    tasks=[...],
    process=Process.sequential,
    memory=True,
    verbose=True,
    embedder={
        "provider": "ollama",
        "config": {
            "model": "mxbai-embed-large"
        }
    }
)
```

### Google AI 임베딩 사용하기

#### 준비사항

Google AI 임베딩을 사용하기 전에 다음 사항을 확인한다:

* Gemini API 접근 권한
* 필요한 API 키와 권한

*pyproject.toml* 의존성을 업데이트해야 한다:

```YAML theme={null}
dependencies = [
    "google-generativeai>=0.8.4", #2025년 1월 기준 메인 버전 - crewai v.0.100.0 및 crewai-tools 0.33.0
    "crewai[tools]>=0.100.0,<1.0.0"
]
```

```python theme={null}
from crewai import Crew, Agent, Task, Process

my_crew = Crew(
    agents=[...],
    tasks=[...],
    process=Process.sequential,
    memory=True,
    verbose=True,
    embedder={
        "provider": "google",
        "config": {
            "api_key": "<YOUR_API_KEY>",
            "model": "<model_name>"
        }
    }
)
```

### Azure OpenAI 임베딩 사용하기

```python theme={null}
from chromadb.utils.embedding_functions import OpenAIEmbeddingFunction
from crewai import Crew, Agent, Task, Process

my_crew = Crew(
    agents=[...],
    tasks=[...],
    process=Process.sequential,
    memory=True,
    verbose=True,
    embedder={
        "provider": "openai",
        "config": {
            "api_key": "YOUR_API_KEY",
            "api_base": "YOUR_API_BASE_PATH",
            "api_version": "YOUR_API_VERSION",
            "model_name": 'text-embedding-3-small'
        }
    }
)
```

### Vertex AI 임베딩 사용하기

```python theme={null}
from chromadb.utils.embedding_functions import GoogleVertexEmbeddingFunction
from crewai import Crew, Agent, Task, Process

my_crew = Crew(
    agents=[...],
    tasks=[...],
    process=Process.sequential,
    memory=True,
    verbose=True,
    embedder={
        "provider": "vertexai",
        "config": {
            "project_id": "YOUR_PROJECT_ID",
            "region": "YOUR_REGION",
            "api_key": "YOUR_API_KEY",
            "model_name": "textembedding-gecko"
        }
    }
)
```

### Cohere 임베딩 사용하기

```python theme={null}
from crewai import Crew, Agent, Task, Process

my_crew = Crew(
    agents=[...],
    tasks=[...],
    process=Process.sequential,
    memory=True,
    verbose=True,
    embedder={
        "provider": "cohere",
        "config": {
            "api_key": "YOUR_API_KEY",
            "model": "<model_name>"
        }
    }
)
```

### VoyageAI 임베딩 사용하기

```python theme={null}
from crewai import Crew, Agent, Task, Process

my_crew = Crew(
    agents=[...],
    tasks=[...],
    process=Process.sequential,
    memory=True,
    verbose=True,
    embedder={
        "provider": "voyageai",
        "config": {
            "api_key": "YOUR_API_KEY",
            "model": "<model_name>"
        }
    }
)
```

### HuggingFace 임베딩 사용하기

```python theme={null}
from crewai import Crew, Agent, Task, Process

my_crew = Crew(
    agents=[...],
    tasks=[...],
    process=Process.sequential,
    memory=True,
    verbose=True,
    embedder={
        "provider": "huggingface",
        "config": {
            "api_url": "<api_url>",
        }
    }
)
```

### Watson 임베딩 사용하기

```python theme={null}
from crewai import Crew, Agent, Task, Process

# 참고: Watson 임베딩을 사용하려면 `ibm_watsonx_ai`를 설치하고 임포트해야 한다.

my_crew = Crew(
    agents=[...],
    tasks=[...],
    process=Process.sequential,
    memory=True,
    verbose=True,
    embedder={
        "provider": "watson",
        "config": {
            "model": "<model_name>",
            "api_url": "<api_url>",
            "api_key": "<YOUR_API_KEY>",
            "project_id": "<YOUR_PROJECT_ID>",
        }
    }
)
```

### Amazon Bedrock 임베딩 사용하기

```python theme={null}
# 참고: Bedrock 임베딩을 사용하려면 `boto3`가 설치되어 있어야 한다.

import os
import boto3
from crewai import Crew, Agent, Task, Process

boto3_session = boto3.Session(
    region_name=os.environ.get("AWS_REGION_NAME"),
    aws_access_key_id=os.environ.get("AWS_ACCESS_KEY_ID"),
    aws_secret_access_key=os.environ.get("AWS_SECRET_ACCESS_KEY")
)

my_crew = Crew(
    agents=[...],
    tasks=[...],
    process=Process.sequential,
    memory=True,
    embedder={
        "provider": "bedrock",
        "config":{
            "session": boto3_session,
            "model": "amazon.titan-embed-text-v2:0",
            "vector_dimension": 1024
        }
    },
    verbose=True
)
```

### 커스텀 임베딩 함수 추가하기

```python theme={null}
from crewai import Crew, Agent, Task, Process
from chromadb import Documents, EmbeddingFunction, Embeddings

# 커스텀 임베딩 함수 생성
class CustomEmbedder(EmbeddingFunction):
    def __call__(self, input: Documents) -> Embeddings:
        # 임베딩 생성
        return [1, 2, 3] # 더미 임베딩

my_crew = Crew(
    agents=[...],
    tasks=[...],
    process=Process.sequential,
    memory=True,
    verbose=True,
    embedder={
        "provider": "custom",
        "config": {
            "embedder": CustomEmbedder()
        }
    }
)
```

### 메모리 초기화

```shell theme={null}
crewai reset-memories [OPTIONS]
```

#### 메모리 옵션 초기화

| 옵션                        | 설명                | 타입        | 기본값   |
| :------------------------ | :---------------- | :-------- | :---- |
| `-l`, `--long`            | 장기 메모리 초기화.       | 플래그 (불리언) | False |
| `-s`, `--short`           | 단기 메모리 초기화.       | 플래그 (불리언) | False |
| `-e`, `--entities`        | 엔티티 메모리 초기화.      | 플래그 (불리언) | False |
| `-k`, `--kickoff-outputs` | 최신 킥오프 작업 출력 초기화. | 플래그 (불리언) | False |
| `-a`, `--all`             | 모든 메모리 초기화.       | 플래그 (불리언) | False |

## CrewAI 메모리 시스템의 장점

* 🦾 **적응형 학습:** 크루는 시간이 지남에 따라 더 효율적으로 변한다. 새로운 정보에 적응하고 작업 방식을 개선한다.
* 🫡 **향상된 개인화:** 메모리 기능을 통해 에이전트는 사용자 선호도와 이전 상호작용을 기억한다. 이를 통해 개인화된 경험을 제공한다.
* 🧠 **문제 해결 능력 향상:** 풍부한 메모리 저장소에 접근할 수 있어 에이전트는 과거 학습 내용과 상황별 통찰력을 바탕으로 더 나은 결정을 내린다.

## 결론

CrewAI의 메모리 시스템을 여러분의 프로젝트에 통합하는 것은 간단하다. 제공되는 메모리 컴포넌트와 설정을 활용해 에이전트가 상호작용을 기억하고, 추론하고, 학습할 수 있는 능력을 빠르게 부여할 수 있다. 이를 통해 새로운 수준의 지능과 기능을 구현할 수 있다.