4.6. 워크스페이스 & 메모리¶

각 Squad에는 전용 워크스페이스 디렉터리와 에이전트별 메모리 시스템이 있어 작업 간 컨텍스트 유지와 지식 공유가 가능합니다.

워크스페이스¶

워크스페이스는 Squad가 소유하는 파일 시스템의 디렉터리입니다. 플랜, 태스크 출력, 에이전트 파일, 메타데이터를 저장합니다.

워크스페이스 구조¶

Squad가 생성되면 워크스페이스가 구조화된 레이아웃으로 초기화됩니다:

my-squad-workspace/
├── .squad-config.json    # Squad 매니페스트 (복원용)
├── plans/                # 생성된 플랜
├── tasks/                # 태스크 출력 및 산출물
├── agents/               # 에이전트별 파일
│   ├── planner/
│   │   └── memory.md     # 플래너의 메모리 파일
│   ├── developer/
│   │   └── memory.md     # 개발자의 메모리 파일
│   └── reviewer/
│       └── memory.md     # 리뷰어의 메모리 파일
└── logs/                 # 실행 로그

파일 탐색¶

워크스페이스 탐색기를 사용하여 앱 내에서 직접 워크스페이스 디렉터리 트리를 탐색할 수 있습니다:

• 확장/축소로 파일 트리 탐색
• 텍스트, 마크다운, JSON 파일 인라인 미리 보기
• 파일 크기와 수정 타임스탬프 확인
• 전체 워크스페이스 크기와 파일 수 모니터링

파일 검색¶

워크스페이스 검색을 사용하여 워크스페이스의 모든 파일에서 콘텐츠를 찾을 수 있습니다. 전체 텍스트 검색을 수행하고 하이라이트된 결과와 함께 일치하는 파일을 반환합니다.

워크스페이스 상태¶

모니터링 대시보드에서 워크스페이스 상태 지표를 표시합니다:

메모리¶

Squad의 각 에이전트는 영구 메모리 파일을 가질 수 있습니다 — 섹션으로 구성된 마크다운 문서로, 에이전트가 각 태스크 시작 시 읽고 실행 중에 업데이트할 수 있습니다.

메모리 작동 방식¶

1. 에이전트가 태스크를 시작하면 메모리 파일이 컨텍스트에 로드됩니다
2. 실행 중에 에이전트가 새로운 관찰, 결정, 학습 패턴을 메모리에 기록할 수 있습니다
3. N번의 대화 턴마다(추출 트리거 간격으로 설정) 앱이 최근 채팅에서 인사이트를 자동으로 추출해 Insights 섹션에 추가합니다. 에이전트가 도구를 호출하지 않아도 됩니다
4. 업데이트된 메모리는 태스크 간에 유지되어 시간이 지남에 따라 지식 기반을 구축합니다

자동 추출¶

에이전트에 memory_enabled가 설정되면 백엔드가 trigger_interval마다 LLM 추출을 실행합니다. 추출된 각 사실은 동일한 LLM 단계에서 프로젝트 범위(Layer B) 또는 경험적(Layer A) 으로 분류되고, 해당 분류에 맞는 저장소로 이중 라우팅됩니다. 이 작업은 백그라운드에서 비동기로 실행되므로 채팅 응답을 차단하지 않습니다.

라우터가 실행 중이 아니거나 메시지 수가 트리거 간격보다 적으면 추출은 건너뜁니다.

Layer B: 프로젝트 범위 메모리¶

프로젝트 범위 사실은 에이전트의 워크스페이스 메모리 파일({workspace}/memory/{agent}.md)의 Insights 섹션에 기록됩니다. 현재 프로젝트 안에서만 의미 있는 정보들, 즉 파일 레이아웃, 진행 중인 결정, 프로젝트 고유 규칙 등이 여기 해당합니다. 이 정보들은 다른 Squad나 프로젝트로 이어지지 않습니다.

Layer A: 경험적 메모리¶

경험적 사실은 프로젝트를 넘어 지속되는 학습 내용으로, 사용자 선호도, 재사용 가능한 기술, 사용자와 관련된 고유 명칭 등 향후 Squad에서도 에이전트와 함께 이동하는 정보입니다. 각 에이전트는 메모리 페이지에서 확인할 수 있는 전용 글로벌 MemoryNamespace를 가지며, 이름은 Agent Experience: <에이전트 이름> 형태입니다.

네임스페이스의 정체성은 에이전트의 소스 프로필 ID를 기준으로 결정됩니다. 동일한 프로필로 생성된 두 Squad는 하나의 Layer-A 네임스페이스를 공유하므로, 에이전트는 프로젝트마다 처음부터 시작하는 대신 경험을 계속 축적해 나갑니다. 소스 프로필이 없는 에이전트는 (squad, agent-id) 조합을 기준으로 별도의 네임스페이스를 사용하며, 해당 Squad 내에만 경험적 메모리가 유지됩니다.

Layer-A 네임스페이스는 기본적으로 비활성화 상태로 생성됩니다. 글로벌 메모리 주입 파이프라인은 활성화된 네임스페이스만 표시하므로, 메모리 페이지에서 직접 활성화하기 전까지는 에이전트의 경험적 메모리가 다른 에이전트의 채팅이나 메인 채팅에 자동으로 주입되지 않습니다. 에이전트별 채팅 경로(아래 설명)는 활성화 플래그를 우회해 Layer-A 콘텐츠를 직접 읽으므로, 토글 상태에 관계없이 에이전트는 자신의 축적된 경험을 매 채팅에서 볼 수 있습니다.

메모리 읽기 되돌림 (Phase 3)¶

에이전트 채팅에서 메시지를 보낼 때마다, 백엔드는 에이전트의 Layer-A와 Layer-B 메모리를 ## Agent Memory 섹션으로 묶어 정적 squad 컨텍스트 헤더 뒤에 붙인 시스템 프롬프트를 새로 조립합니다. 에이전트는 별도의 프롬프트 작성 없이도 매 채팅 턴마다 자신의 경험적 메모리와 워크스페이스 사실을 볼 수 있습니다.

주입되는 메모리 블록의 합산 예산은 설정의 memory.maxTokens로 조정됩니다. 이 예산은 Layer A에 60%, Layer B에 40%로 배분됩니다. 경험적 메모리는 최근 대화에서 이미 확인할 수 있는 워크스페이스 사실보다 여러 턴에 걸쳐 재사용 가능성이 높기 때문에 Layer A가 우선권을 갖습니다. 예산이 2 이상이면 Layer B는 최소 1토큰을 받으므로, 어느 레이어도 조용히 무시되지 않습니다.

이 에이전트별 예산은 활성화된 네임스페이스로 구성된 글로벌 [Supplementary Context] 블록과 독립적입니다. memory.maxTokens = 2000으로 설정했을 때 채팅에는 글로벌 컨텍스트 최대 2000토큰과 에이전트별 Layer-A + Layer-B 메모리 최대 2000토큰이 나란히 포함될 수 있습니다.

Phase 3 이후에도 Layer-A 네임스페이스는 글로벌 파이프라인에서 enabled: false 상태를 유지합니다. 글로벌 파이프라인은 크로스 에이전트 격리를 유지하고, Layer-A 네임스페이스의 활성화 플래그를 무시하고 읽는 경로는 에이전트별 채팅 경로뿐입니다.

메모리 섹션¶

메모리 파일은 명명된 섹션으로 구성됩니다:

# 프로젝트 컨텍스트
이 프로젝트는 TypeScript와 Zustand를 사용하는 React를 사용합니다.

# 코딩 규칙
- 훅을 사용하는 함수형 컴포넌트 사용
- CSS 클래스에 BEM 네이밍 적용
- 모든 API 호출은 src/lib/api.ts를 통해 수행

# 내린 결정
- 인증에 JWT 선택 (태스크 #3)
- 데이터베이스 스키마는 snake_case 컬럼명 사용 (태스크 #5)

에이전트는 나머지 메모리 파일에 영향을 주지 않고 개별 섹션을 읽거나, 추가하거나, 교체할 수 있습니다.

크로스 에이전트 메모리 검색¶

메모리 검색 기능을 사용하면 모든 에이전트의 메모리 파일을 동시에 검색할 수 있습니다:

• 검색 쿼리를 입력하여 일치하는 콘텐츠 찾기
• 특정 에이전트 또는 메모리 섹션으로 필터링
• 대소문자 구분 매칭 토글
• 더 나은 이해를 위해 각 일치 항목 주변의 컨텍스트 라인 확인

이 기능은 특정 에이전트가 이전 태스크에서 기록한 결정, 규칙, 지식을 찾는 데 유용합니다.

메모리 활성화 시기¶