Skip to main content
Deep agent는 메모리를 오프로드하기 위한 로컬 파일시스템을 제공합니다. 이 파일시스템은 상태에 저장되므로 단일 스레드에만 일시적으로 존재하며, 대화가 종료되면 파일이 손실됩니다. LangGraph Store를 제공하고 use_longterm_memory=True를 설정하여 deep agent를 장기 메모리로 확장할 수 있습니다. 이를 통해 스레드와 대화 간에 지속되는 영구 스토리지를 사용할 수 있습니다.

설정

from deepagents import create_deep_agent
from langgraph.store.memory import InMemoryStore

store = InMemoryStore()  # 또는 다른 Store 객체
agent = create_deep_agent(
    store=store,
    use_longterm_memory=True
)

작동 방식

장기 메모리가 활성화되면 deep agent는 두 개의 별도 파일시스템을 유지합니다:

1. 단기(일시적) 파일시스템

  • 에이전트의 상태에 저장됨
  • 단일 스레드 내에서만 유지됨
  • 스레드가 종료되면 파일이 손실됨
  • 표준 경로를 통해 접근: /notes.txt

2. 장기(영구) 파일시스템

  • LangGraph Store에 저장됨
  • 모든 스레드와 대화에 걸쳐 유지됨
  • 파일이 무기한 존재함
  • 특수 접두사를 통해 접근: /memories/notes.txt

/memories/ 경로 규칙

장기 메모리의 핵심은 /memories/ 경로 접두사입니다:
  • /memories/로 시작하는 경로의 파일은 Store에 저장됨(영구)
  • 이 접두사가 없는 파일은 일시적 상태로 유지됨
  • 모든 파일시스템 도구(ls, read_file, write_file, edit_file)가 두 파일시스템 모두에서 작동함
# 일시적 파일 (스레드 종료 후 손실)
agent.invoke({
    "messages": [{"role": "user", "content": "Write draft to /draft.txt"}]
})

# 영구 파일 (스레드 간에 유지)
agent.invoke({
    "messages": [{"role": "user", "content": "Save final report to /memories/report.txt"}]
})

스레드 간 지속성

/memories/의 파일은 모든 스레드에서 접근할 수 있습니다:
import uuid

# 스레드 1: 장기 메모리에 쓰기
config1 = {"configurable": {"thread_id": str(uuid.uuid4())}}
agent.invoke({
    "messages": [{"role": "user", "content": "Save my preferences to /memories/preferences.txt"}]
}, config=config1)

# 스레드 2: 장기 메모리에서 읽기 (다른 대화!)
config2 = {"configurable": {"thread_id": str(uuid.uuid4())}}
agent.invoke({
    "messages": [{"role": "user", "content": "What are my preferences?"}]
}, config=config2)
# 에이전트가 첫 번째 스레드의 /memories/preferences.txt를 읽을 수 있음

사용 사례

사용자 설정

세션 간에 지속되는 사용자 설정을 저장합니다:
agent = create_deep_agent(
    store=store,
    use_longterm_memory=True,
    system_prompt="""When users tell you their preferences, save them to
    /memories/user_preferences.txt so you remember them in future conversations."""
)

자기 개선형 지침

에이전트가 피드백을 기반으로 자체 지침을 업데이트할 수 있습니다:
agent = create_deep_agent(
    store=store,
    use_longterm_memory=True,
    system_prompt="""You have a file at /memories/instructions.txt with additional
    instructions and preferences.

    Read this file at the start of conversations to understand user preferences.

    When users provide feedback like "please always do X" or "I prefer Y",
    update /memories/instructions.txt using the edit_file tool."""
)
시간이 지남에 따라 지침 파일에 사용자 설정이 축적되어 에이전트가 개선되는 데 도움이 됩니다.

지식 베이스

여러 대화에 걸쳐 지식을 구축합니다:
# 대화 1: 프로젝트에 대해 학습
agent.invoke({
    "messages": [{"role": "user", "content": "We're building a web app with React. Save project notes."}]
})

# 대화 2: 해당 지식 사용
agent.invoke({
    "messages": [{"role": "user", "content": "What framework are we using?"}]
})
# 에이전트가 이전 대화의 /memories/project_notes.txt를 읽음

연구 프로젝트

세션 간에 연구 상태를 유지합니다:
research_agent = create_deep_agent(
    store=store,
    use_longterm_memory=True,
    system_prompt="""You are a research assistant.

    Save your research progress to /memories/research/:
    - /memories/research/sources.txt - List of sources found
    - /memories/research/notes.txt - Key findings and notes
    - /memories/research/report.md - Final report draft

    This allows research to continue across multiple sessions."""
)

Store 구현

모든 LangGraph BaseStore 구현이 작동합니다:

InMemoryStore (개발용)

테스트 및 개발에 적합하지만 재시작 시 데이터가 손실됩니다:
from langgraph.store.memory import InMemoryStore

store = InMemoryStore()
agent = create_deep_agent(store=store, use_longterm_memory=True)

PostgresStore (프로덕션용)

프로덕션에서는 영구 저장소를 사용하세요:
from langgraph.store.postgres import PostgresStore
import os

store = PostgresStore(connection_string=os.environ["DATABASE_URL"])
agent = create_deep_agent(store=store, use_longterm_memory=True)

모범 사례

설명이 포함된 경로 사용

명확하고 계층적인 경로로 장기 파일을 구성하세요:
# ✅ 좋음: 체계적이고 설명적임
/memories/user_preferences/language.txt
/memories/projects/project_alpha/status.txt
/memories/research/quantum_computing/sources.txt

# ❌ 나쁨: 일반적이고 비체계적임
/memories/temp.txt
/memories/data.txt
/memories/file1.txt

지속되는 내용 문서화

시스템 프롬프트에서 장기 저장소와 단기 저장소를 언제 사용할지 명확히 하세요:
system_prompt="""You have access to two types of storage:

SHORT-TERM (paths without /memories/):
- Current conversation notes
- Temporary scratch work
- Draft documents

LONG-TERM (paths starting with /memories/):
- User preferences and settings
- Completed reports and documents
- Knowledge that should persist across conversations
- Project state and progress

Always use /memories/ for information that should survive beyond this conversation."""

assistant ID별로 저장소 격리

다중 테넌트 애플리케이션의 경우 assistant_id를 제공하여 저장소를 격리하세요:
config = {
    "configurable": {
        "thread_id": "thread-123",
    },
    "metadata": {
        "assistant_id": "user-456"  # 네임스페이스 격리
    }
}

agent.invoke({"messages": [...]}, config=config)
각 어시스턴트는 Store에서 자체 네임스페이스를 가지므로 교차 오염이 방지됩니다.

프로덕션에서 영구 저장소 사용

# ❌ 개발용만 - 재시작 시 데이터 손실
store = InMemoryStore()

# ✅ 프로덕션용 - 데이터 유지
from langgraph.store.postgres import PostgresStore
store = PostgresStore(connection_string=os.environ["DATABASE_URL"])

파일 목록 조회

ls 도구는 두 파일시스템의 파일을 모두 보여줍니다:
agent.invoke({
    "messages": [{"role": "user", "content": "List all files"}]
})

# 예시 출력:
# Transient files:
# - /draft.txt
# - /temp_notes.txt
#
# Long-term files:
# - /memories/user_preferences.txt
# - /memories/project_status.txt
Store의 파일은 목록에 /memories/ 접두사가 붙어 표시됩니다.

제한 사항

Store가 필수

장기 메모리를 활성화할 때 Store를 제공해야 합니다:
# ❌ 이는 오류가 발생함
agent = create_deep_agent(use_longterm_memory=True)  # store가 누락됨!

# ✅ 올바름
agent = create_deep_agent(
    use_longterm_memory=True,
    store=InMemoryStore()
)

에이전트는 올바른 경로를 사용해야 함

에이전트는 지속성을 위해 /memories/ 접두사를 사용하는 방법을 학습해야 합니다. 시스템 프롬프트가 이를 가르치지만 에이전트가 지침을 따라야 합니다.

자동 정리 없음

장기 파일은 무기한 유지됩니다. 내장된 TTL이나 자동 정리가 없습니다. 필요한 경우 정리 전략을 구현해야 합니다.
Connect these docs programmatically to Claude, VSCode, and more via MCP for real-time answers.