데이터 및 저장소

데이터가 어디에 저장되는지, 누가 무엇을 읽을 수 있는지, 그리고 고객 대면 페이지가 실수로 내부 데이터를 보지 못하도록 에이전트가 따르는 규칙입니다.

세 가지 저장 위치

1. 워크스페이스 (~/workspace/)

에이전트가 실행되는 파일 시스템입니다. 마크다운 초안, 생성된 자산, 사용자 정의 스킬, 작업, 임시 공간 및 이러한 문서가 모두 여기에 저장됩니다.

• 소유자: agent Linux 사용자(에이전트 자체).
• 채팅에서 접근 가능. 콘솔 프로세스나 공개 사이트 프로세스에서는 접근 불가.
• 두 가지 일반적인 경로:
• ~/workspace/uploads/: 채팅에 붙여넣은 파일이 여기에 저장됩니다.
• ~/workspace/downloads/: 에이전트가 워크스페이스 UI를 통해 다운로드용으로 등록한 파일. nginx에 의해 제한된 URL로 제공됩니다.

2. PostgreSQL (세 개의 데이터베이스)

구조화된 모든 것을 위한 영구 상태입니다. 애플리케이션 상태에 SQLite나 디스크 기반 JSON을 사용하지 않습니다.

무엇이 어디에 들어가는지:

• console_db: 내부 전용 상태입니다. 고객 목록, 거래 단계, 내부 점수 테이블, 감사 로그가 포함됩니다. 공개 사이트는 이 데이터베이스에 접근할 수 없으며, REVOKE는 단순한 관례가 아닌 데이터베이스 역할 계층에서 적용됩니다.
• site_db: 공개 사이트가 렌더링하는 콘텐츠입니다. 사전 계산된 보고서, 문서 페이지, 페이지 렌더링 시 빠르게 읽어야 하는 모든 항목이 포함됩니다. 콘솔이 여기에 쓰고, 사이트가 읽습니다.
• console_site_db: 명시적인 교차 표면 채널입니다. 콘솔이 검토 대기열을 작성하고, 사이트가 승인된 항목을 렌더링하며, 사이트가 상호작용 신호를 다시 작성하고, 콘솔이 이를 읽습니다.

3. 메모리와 진행 상황

워크스페이스의 두 가지 특수 파일:

• ~/workspace/.memory.md: read at the start of every chat. Use "remember this: X" to append.
• ~/workspace/progress.md: change log. The agent appends after meaningful changes; you can read it to reconstruct what happened.

이는 의도적으로 마크다운 형식입니다. grep으로 검색하고, 버전 관리하고, 직접 편집하고, 다시 grep으로 검색할 수 있습니다.

하나가 아닌 세 개의 데이터베이스를 사용하는 이유

두 가지 이유가 있습니다.

1. 표면 분리. 공개 사이트 방문자가 원칙적으로 사이트가 인증하는 데이터베이스 역할을 쿼리하는 방법을 찾을 수 있습니다. 해당 역할이 site_db에만 액세스할 수 있다면, 유출 시 영향 범위는 이미 공개하기로 결정한 데이터로 제한됩니다.
2. 의도의 명확성. 에이전트가 콘솔 앱을 작성할 때는 console_db를 사용해야 한다는 것을 알고 있습니다. 사이트 페이지를 작성할 때는 site_db를 사용합니다. 교차 표면 워크플로를 구축할 때는 console_site_db를 사용합니다. "이 테이블을 공개해야 하나?"라는 우발적인 질문이 발생하지 않습니다.

에이전트는 이러한 규칙을 어기려 하지 않습니다. "이 콘솔 페이지를 공개적으로 노출해줘"라고 요청하면, 사이트에서 console_db에 직접 접근하는 대신 console_site_db를 통해 데이터를 이동하고 사이트의 읽기 경로를 재구축해야 한다고 알려줍니다.

데이터베이스 작업

매번 반복되는 패턴:

• src/db.py에서 가져온 SQLAlchemy 세션 (앱별 공유 모듈).
• Pydantic 모델이 모든 입력과 모든 API 경계를 보호합니다.
• SQLAlchemy가 과도한 경우에만 원시 psycopg2 사용 (읽기 전용 토큰 게이트 조회, 간단한 스크립트).

새로운 앱의 상단에 CREATE TABLE IF NOT EXISTS 문이 표시됩니다. 에이전트는 스키마를 코드로 취급합니다. 각 앱은 자체 테이블을 선언합니다. 플랫폼 마이그레이션 시스템은 없으며, 새로운 컬럼은 ALTER TABLE로 추가되고 에이전트가 변경 사항을 기록합니다.

ClickHouse는 어떤가요

ClickHouse는 PostgreSQL이 느릴 수 있는 분석 작업을 위해 로컬에서 사용할 수 있습니다. 수백만 행에 대한 시계열 롤업, 컬럼 기반 집계 등이 그 예입니다. 에이전트는 ClickHouse를 사용하기 전에 ClickHouse 스킬을 읽고 의도적으로 선택하며, 그 이유를 알려줍니다. 기본값은 PostgreSQL로 유지됩니다.

존재하지 않는 곳

• 플랫폼 관리 객체 스토리지 없음. 50MB PDF나 동영상을 저장하려면 ~/workspace/downloads/에 파일로 저장하거나(nginx로 제어) Postgres의 BYTEA 컬럼에 저장합니다(작은 아티팩트에 적합).
• 시크릿용 환경 변수 없음. 자격 증명은 타입이 지정된 시크릿 스토어에 저장되며, 서피스와 커넥터로 범위가 지정됩니다. 에이전트는 이를 파일이나 데이터베이스 컬럼에 복사하지 않습니다.
• 워크스페이스 UI가 노출하는 것 이상의 "플랫폼 설정" 페이지 없음. 스케줄, 모드, 승인은 모두 명시적인 토글입니다.

데이터 수명 주기

• 생성한 파일은 삭제하기 전까지 유지됩니다. 에이전트는 워크스페이스를 자동으로 정리하지 않습니다.
• 데이터베이스 행은 사용자(또는 명시적 정리 작업)가 제거하기 전까지 유지됩니다. 에이전트는 "매주 일요일마다 90일 이상 된 vsg_runs 행 삭제"와 같이 요청하면 정리 작업을 작성합니다.
• 메모리 및 진행 상황 파일은 시간이 지남에 따라 증가합니다. 에이전트는 메모리가 복잡해지면 가끔 정리를 제안합니다.
• 커넥터 감사 로그는 플랫폼에서 보관됩니다. 로그를 탐색할 수 있지만 삭제할 수는 없습니다.

내부 작동 방식. 각 Postgres 역할은 Unix 소켓 피어 인증을 통해 인증됩니다(OS 사용자가 역할 이름과 일치). 유출될 비밀번호도, 잘못 구성될 연결 문자열도 없습니다. 권한 부여와 취소는 명시적이고 가시적입니다. system_db 데이터베이스는 플랫폼 내부(api-proxy, 커넥터 서비스, 브리지)를 위해 존재하며, 어떤 표면도 이에 연결되지 않습니다.