MemoRizz 프로젝트 상세 소개

프로젝트 개요

MemoRizz는 AI 애플리케이션을 위해 특별히 설계된 Python 메모리 관리 라이브러리로, AI 에이전트에게 영구적이고, 문맥을 인지하며, 의미론적 검색이 가능한 정보 저장 기능을 제공합니다. 이 프로젝트는 MongoDB와 벡터 임베딩 기술의 원활한 통합을 통해 대화 기록 추적, 도구 사용 관리, 일관된 역할 유지 등 복잡한 인지 기능을 에이전트에 부여합니다.

⚠️ 중요 경고: MemoRizz는 교육 목적으로만 사용되는 실험적인 라이브러리입니다. 프로덕션 환경이나 민감한 데이터에는 사용하지 않는 것을 권장합니다.

핵심 기능

🧠 영구 메모리

• AI 에이전트가 세션 간에 기억을 유지하도록 합니다.
• 장기 정보 저장 및 검색을 지원합니다.
• 문맥을 인지하는 메모리 관리.

🔍 의미론적 검색

• 자연어를 사용하여 관련 정보를 찾습니다.
• 벡터 임베딩 기반의 유사성 검색.
• MongoDB Atlas 벡터 검색 통합.

🛠️ 도구 통합

• 함수의 자동 발견 및 실행.
• Python 함수를 LLM 호출 가능한 도구로 변환.
• 도구의 의미론적 색인 및 자연어 발견.

👤 역할 시스템

• 일관되고 전문화된 에이전트 역할 생성.
• 에이전트 행동 및 응답 스타일 사용자 정의.
• 역할 배경 및 목표 설정.

📊 벡터 검색

• MongoDB Atlas 벡터 검색을 통한 효율적인 검색.
• 저장된 정보의 자동 임베딩 및 색인화.
• 다양한 메모리 유형 분류 지원.

시스템 아키텍처

┌─────────────────┐
│ MemAgent        │ ← 고급 에이전트 인터페이스
├─────────────────┤
│ Persona         │ ← 에이전트 개성 및 행동
├─────────────────┤
│ Toolbox         │ ← 함수 등록 및 발견
├─────────────────┤
│ Memory Provider │ ← 저장 추상화 계층
├─────────────────┤
│ Vector Search   │ ← 의미론적 유사성 및 검색
├─────────────────┤
│ MongoDB         │ ← 영구 저장 백엔드
└─────────────────┘

설치 요구 사항

• Python 3.7+
• MongoDB Atlas 계정 (또는 벡터 검색이 가능한 로컬 MongoDB)
• OpenAI API 키 (임베딩 및 LLM 기능용)

설치 방법

pip install memorizz

기본 사용 예시

1. 기본 에이전트 설정

import os
from memorizz.memory_provider.mongodb.provider import MongoDBConfig, MongoDBProvider
from memorizz.memagent import MemAgent
from memorizz.llms.openai import OpenAI

# API 키 설정
os.environ["OPENAI_API_KEY"] = "your-openai-api-key"

# MongoDB 메모리 제공자 구성
mongodb_config = MongoDBConfig(uri="your-mongodb-atlas-uri")
memory_provider = MongoDBProvider(mongodb_config)

# MemAgent 생성
agent = MemAgent(
    model=OpenAI(model="gpt-4"),
    instruction="You are a helpful assistant with persistent memory.",
    memory_provider=memory_provider
)

# 대화 시작 - 에이전트는 세션 간에 기억을 유지합니다.
response = agent.run("Hello! My name is John and I'm a software engineer.")
print(response)

# 나중에 다른 세션에서...
response = agent.run("What did I tell you about myself?")
print(response)  # 에이전트는 John이 소프트웨어 엔지니어임을 기억합니다.

2. 역할 시스템 사용

from memorizz.persona import Persona

# 기술 전문가 역할 생성
tech_expert = Persona(
    name="TechExpert",
    role="Senior Software Engineer",
    goals="Help developers solve complex technical problems with detailed explanations.",
    background="10+ years experience in Python, AI/ML, and distributed systems."
)

# 역할을 에이전트에 적용
agent.set_persona(tech_expert)
agent.save()

# 이제 에이전트는 기술 전문가로서 응답할 것입니다.
response = agent.run("How should I design a scalable microservices architecture?")

3. 도구 통합

from memorizz.database.mongodb import MongoDBTools, MongoDBToolsConfig

# 도구 데이터베이스 구성
tools_config = MongoDBToolsConfig(
    uri="your-mongodb-atlas-uri",
    database_name="my_tools_db"
)

# 데코레이터를 사용하여 도구 등록
with MongoDBTools(tools_config) as tools:
    toolbox = tools.mongodb_toolbox()
    
    @toolbox
    def calculate_compound_interest(principal: float, rate: float, time: int) -> float:
        """Calculate compound interest for financial planning."""
        return principal * (1 + rate) ** time
    
    @toolbox
    def get_weather(city: str) -> str:
        """Get current weather for a city."""
        # 당신의 날씨 API 통합 코드
        return f"Weather in {city}: 72°F, sunny"

# 에이전트에 도구 추가
agent.add_tool(toolbox=tools)

# 에이전트는 이제 이러한 도구를 자동으로 발견하고 사용할 수 있습니다.
response = agent.run("What's the weather in San Francisco and calculate interest on $1000 at 5% for 3 years?")

메모리 유형

MemoRizz는 정보를 구성하기 위해 다양한 메모리 범주를 지원합니다:

• Conversation: 채팅 기록 및 대화 문맥
• Task: 목표 지향 정보 및 진행 상황 추적
• Workflow: 다단계 프로세스 정보
• General: 사실적 지식 및 선언적 정보
• Working: 임시 처리 공간 (LLM 문맥)

고급 기능

메모리 저장 및 검색

# 자동 임베딩으로 정보 저장
agent.store_memory("I prefer Python for backend development", memory_type="general")

# 나중에, 의미론적으로 관련된 쿼리가 이 정보를 검색할 것입니다.
response = agent.run("What programming languages do I like?")
# 에이전트는 저장된 선호도를 찾아 사용할 것입니다.

메타데이터를 사용한 메모리 제어

# 메타데이터와 함께 정보 저장
agent.store_memory(
    content="Completed project X with React and Node.js",
    memory_type="task",
    metadata={"project": "X", "technologies": ["React", "Node.js"]}
)

# 특정 메모리 검색
memories = agent.retrieve_memories(
    query="projects with React",
    memory_type="task",
    limit=5
)

환경 설정

# 필수
export OPENAI_API_KEY="your-openai-api-key"
export MONGODB_URI="your-mongodb-atlas-uri"

# 선택 사항
export MONGODB_DB_NAME="memorizz"  # 기본 데이터베이스 이름

설정 단계

1. MongoDB Atlas 클러스터 생성
2. 클러스터에서 벡터 검색 활성화
3. 에이전트용 데이터베이스 및 컬렉션 생성
4. 연결 문자열 가져오기

일반적인 문제

• MongoDB 연결: Atlas에서 IP가 화이트리스트에 추가되었는지 확인하세요.
• 벡터 검색: 클러스터에서 벡터 검색이 활성화되었는지 확인하세요.
• API 키: OpenAI API 키가 유효하고 크레딧이 있는지 확인하세요.

예시 프로젝트

examples/ 디렉토리에서 완전한 작업 예시를 확인하세요:

• 기본 에이전트: 메모리가 있는 간단한 대화 에이전트
• 전문 에이전트: 역할을 가진 기술 전문가
• 도구 통합: 사용자 정의 함수 호출이 있는 에이전트
• 메모리 관리: 고급 메모리 저장 및 검색

기술 학습 가치

이 라이브러리는 다음 핵심 개념을 보여줍니다:

• AI 에이전트 아키텍처: 메모리, 추론 및 도구 사용
• 벡터 데이터베이스: 의미론적 검색 및 검색
• LLM 통합: 함수 호출 및 문맥 관리
• 소프트웨어 설계: 명확한 추상화 및 확장 가능한 아키텍처