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

Setup

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

store = InMemoryStore()  # Or any other Store object
agent = create_deep_agent(
    store=store,
    use_longterm_memory=True
)

작동 방식

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

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

  • agent의 state에 저장됨
  • 단일 스레드 내에서만 유지됨
  • 스레드가 종료되면 파일이 손실됨
  • 표준 경로를 통해 액세스: /notes.txt

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

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

/memories/ 경로 규칙

장기 메모리의 핵심은 /memories/ 경로 접두사입니다:
  • /memories/로 시작하는 경로의 파일은 Store에 저장됨(영구적)
  • 이 접두사가 없는 파일은 일시적인 state에 유지됨
  • 모든 파일시스템 tool(ls, read_file, write_file, edit_file)은 두 가지 모두에서 작동함
# Transient file (lost after thread ends)
agent.invoke({
    "messages": [{"role": "user", "content": "Write draft to /draft.txt"}]
})

# Persistent file (survives across threads)
agent.invoke({
    "messages": [{"role": "user", "content": "Save final report to /memories/report.txt"}]
})

스레드 간 지속성

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

# Thread 1: Write to long-term memory
config1 = {"configurable": {"thread_id": str(uuid.uuid4())}}
agent.invoke({
    "messages": [{"role": "user", "content": "Save my preferences to /memories/preferences.txt"}]
}, config=config1)

# Thread 2: Read from long-term memory (different conversation!)
config2 = {"configurable": {"thread_id": str(uuid.uuid4())}}
agent.invoke({
    "messages": [{"role": "user", "content": "What are my preferences?"}]
}, config=config2)
# Agent can read /memories/preferences.txt from the first thread

사용 사례

사용자 선호도

세션 간에 지속되는 사용자 선호도를 저장합니다:
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는 피드백을 기반으로 자체 지침을 업데이트할 수 있습니다:
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."""
)
시간이 지남에 따라 지침 파일에 사용자 선호도가 축적되어 agent가 개선되는 데 도움이 됩니다.

지식 베이스

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

# Conversation 2: Use that knowledge
agent.invoke({
    "messages": [{"role": "user", "content": "What framework are we using?"}]
})
# Agent reads /memories/project_notes.txt from previous conversation

연구 프로젝트

세션 간에 연구 상태를 유지합니다:
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 (프로덕션용)

프로덕션의 경우 영구 store를 사용하세요:
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)

모범 사례

설명적인 경로 사용

명확하고 계층적인 경로로 장기 파일을 구성하세요:
# ✅ Good: Organized and descriptive
/memories/user_preferences/language.txt
/memories/projects/project_alpha/status.txt
/memories/research/quantum_computing/sources.txt

# ❌ Bad: Generic and unorganized
/memories/temp.txt
/memories/data.txt
/memories/file1.txt

지속되는 항목 문서화

system prompt에서 장기 저장소와 단기 저장소를 언제 사용할지 명확히 하세요:
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"  # Namespace isolation
    }
}

agent.invoke({"messages": [...]}, config=config)
각 assistant는 Store에서 자체 namespace를 가지므로 교차 오염을 방지합니다.

프로덕션에서 영구 store 사용

# ❌ Development only - data lost on restart
store = InMemoryStore()

# ✅ Production - data persists
from langgraph.store.postgres import PostgresStore
store = PostgresStore(connection_string=os.environ["DATABASE_URL"])

파일 목록 조회

ls tool은 두 파일시스템의 파일을 모두 표시합니다:
agent.invoke({
    "messages": [{"role": "user", "content": "List all files"}]
})

# Example output:
# Transient files:
# - /draft.txt
# - /temp_notes.txt
#
# Long-term files:
# - /memories/user_preferences.txt
# - /memories/project_status.txt
Store의 파일은 목록에서 /memories/ 접두사가 붙습니다.

제한 사항

Store가 필요함

장기 메모리를 활성화할 때 Store를 제공해야 합니다:
# ❌ This will error
agent = create_deep_agent(use_longterm_memory=True)  # Missing store!

# ✅ Correct
agent = create_deep_agent(
    use_longterm_memory=True,
    store=InMemoryStore()
)

Agent는 올바른 경로를 사용해야 함

Agent는 지속성을 위해 /memories/ 접두사를 사용하는 방법을 학습해야 합니다. system prompt가 이를 가르치지만 agent는 지침을 따라야 합니다.

자동 정리 없음

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