Lucid.so 메모리 백엔드
Lucid 백엔드는 PRX를 관리형 스토리지, 시맨틱 검색, 자동 메모리 조직을 제공하는 AI 기반 메모리 서비스인 Lucid.so에 연결합니다. 호스팅 솔루션을 선호하는 팀을 위한 로컬 SQLite 및 PostgreSQL 백엔드의 대안입니다.
개요
Lucid.so는 AI 에이전트를 위해 설계된 클라우드 호스팅 메모리 플랫폼입니다. 다음을 처리합니다:
- 자동 중복 제거를 갖춘 영구 메모리 스토리지
- 호스팅된 임베딩 모델로 구동되는 시맨틱 검색
- 자동 토픽 클러스터링 및 메모리 조직
- 여러 에이전트 인스턴스 간 크로스 세션 메모리 공유
- 설정 가능한 보존 정책을 갖춘 메모리 생명주기 관리
로컬 백엔드 (SQLite, PostgreSQL)와 달리 Lucid는 데이터베이스 관리가 필요 없습니다. 메모리는 Lucid의 인프라에 저장되고 REST API를 통해 접근합니다.
Lucid 사용 시기
| 시나리오 | 권장 백엔드 |
|---|---|
| 단일 사용자 로컬 에이전트 | SQLite |
| 멀티 사용자 온프레미스 배포 | PostgreSQL |
| 클라우드 우선 팀, 최소 운영 오버헤드 | Lucid |
| 크로스 디바이스 메모리 공유 | Lucid |
| 에어갭 또는 오프라인 환경 | SQLite 또는 PostgreSQL |
| 데이터 거주지에 대한 완전한 제어 | SQLite 또는 PostgreSQL |
사전 요구 사항
- Lucid.so 계정 (lucid.so에서 가입)
- Lucid 대시보드의 API 키
- 워크스페이스 ID (최초 사용 시 자동 생성 또는 기존 것 지정)
빠른 설정
1. API 자격 증명 획득
- Lucid Dashboard에 로그인합니다
- "Settings" > "API Keys"로 이동합니다
- "Memory Read/Write" 권한으로 새 API 키를 생성합니다
- API 키와 워크스페이스 ID를 복사합니다
2. 설정
toml
[memory]
backend = "lucid"
[memory.lucid]
api_key = "luc_xxxxxxxxxxxxxxxxxxxxxxxxxxxx"
workspace_id = "ws_abc123"3. 확인
bash
prx doctor memory이것은 Lucid API와의 연결을 테스트하고 API 키가 필요한 권한을 가지고 있는지 확인합니다.
설정 레퍼런스
| 필드 | 타입 | 기본값 | 설명 |
|---|---|---|---|
api_key | String | 필수 | 메모리 읽기/쓰기 권한이 있는 Lucid.so API 키 |
workspace_id | String | 자동 생성 | 메모리 격리를 위한 워크스페이스 ID. 생략하면 최초 사용 시 자동 생성 |
base_url | String | "https://api.lucid.so/v1" | Lucid API 기본 URL. 자체 호스팅 또는 지역 엔드포인트용 오버라이드 |
timeout_secs | u64 | 30 | HTTP 요청 타임아웃 (초) |
max_retries | u32 | 3 | 일시적 장애에 대한 최대 재시도 횟수 |
retry_backoff_ms | u64 | 500 | 재시도 간 초기 백오프 지연 (지수적) |
batch_size | usize | 50 | 배치 쓰기 요청당 전송할 메모리 수 |
top_k | usize | 10 | 리콜 쿼리의 기본 결과 반환 수 |
similarity_threshold | f64 | 0.5 | 리콜 결과의 최소 유사도 점수 (0.0--1.0) |
auto_topics | bool | true | Lucid의 자동 토픽 클러스터링 활성화 |
retention_days | u64 | 0 | N일보다 오래된 메모리 자동 삭제. 0 = 영구 보관 |
작동 방식
메모리 저장
에이전트가 메모리를 저장하면 PRX가 Lucid API로 전송합니다:
- 메모리 텍스트와 메타데이터가
/memories로 POST 요청으로 전송됩니다 - Lucid가 호스팅된 임베딩 모델로 텍스트를 임베딩합니다
- 메모리가 키워드 검색과 시맨틱 검색 모두에 대해 인덱싱됩니다
auto_topics가 활성화된 경우 Lucid가 자동으로 토픽 레이블을 할당합니다
메모리 리콜
에이전트가 컨텍스트가 필요할 때 PRX가 Lucid를 쿼리합니다:
- 현재 대화 컨텍스트가 리콜 쿼리로 전송됩니다
- Lucid가 하이브리드 검색 (시맨틱 유사도 + 키워드 매칭)을 수행합니다
- 결과가 관련성으로 순위가 매겨지고
similarity_threshold로 필터링됩니다 - Top-K 결과가 텍스트, 메타데이터, 관련성 점수와 함께 반환됩니다
메모리 조직
Lucid는 서버 측 메모리 관리를 제공합니다:
- 중복 제거 -- 유사 중복 메모리가 자동으로 병합됩니다
- 토픽 클러스터링 -- 수동 분류 없이 메모리가 토픽으로 그룹화됩니다
- 압축 -- 오래되거나 관련성이 낮은 메모리를 요약하고 통합할 수 있습니다
- 보존 -- 만료된 메모리가
retention_days에 따라 삭제됩니다
로컬 백엔드와의 비교
| 기능 | SQLite | PostgreSQL | Lucid |
|---|---|---|---|
| 설정 복잡도 | 없음 | 보통 | 최소 (API 키) |
| 데이터 거주지 | 로컬 | 자체 호스팅 | 클라우드 (Lucid 서버) |
| 시맨틱 검색 | 임베딩 애드온 경유 | pgvector 애드온 경유 | 내장 |
| 자동 중복 제거 | 아니요 | 아니요 | 예 |
| 자동 토픽 클러스터링 | 아니요 | 아니요 | 예 |
| 크로스 디바이스 공유 | 아니요 | 예 (네트워크) | 예 (클라우드) |
| 오프라인 작동 | 예 | 예 | 아니요 |
| 비용 | 무료 | 무료 (자체 호스팅) | 무료 티어 + 유료 플랜 |
| 확장성 | ~100K 메모리 | 수백만 | 수백만 (관리형) |
환경 변수
CI/CD 또는 컨테이너화된 배포의 경우 환경 변수로 자격 증명을 설정할 수 있습니다:
bash
export PRX_MEMORY_LUCID_API_KEY="luc_xxxxxxxxxxxxxxxxxxxxxxxxxxxx"
export PRX_MEMORY_LUCID_WORKSPACE_ID="ws_abc123"환경 변수는 설정 파일 값보다 우선합니다.
오류 처리
Lucid 백엔드는 일시적 오류를 우아하게 처리합니다:
- 네트워크 장애 --
max_retries회까지 지수적 백오프로 재시도됩니다 - 속도 제한 -- 429 응답이
Retry-After헤더를 사용한 자동 백오프를 트리거합니다 - 인증 오류 -- 오류로 로깅됩니다; 에이전트는 충돌하지 않고 메모리 없이 계속 작동합니다
- 타임아웃 --
timeout_secs를 초과하는 요청은 취소되고 재시도됩니다
Lucid에 접근할 수 없을 때 PRX는 우아하게 성능이 저하됩니다: 연결이 복구될 때까지 메모리 리콜 없이 에이전트가 작동합니다. 메모리는 손실되지 않습니다 -- 대기 중인 쓰기가 큐에 저장되고 연결이 복구되면 플러시됩니다.
제한 사항
- 인터넷 연결이 필요합니다; 에어갭 환경에는 적합하지 않습니다
- 메모리 데이터가 Lucid의 인프라에 저장됩니다; 컴플라이언스를 위해 데이터 처리 계약을 검토하세요
- 무료 티어에는 스토리지 및 쿼리 제한이 있습니다 (현재 세부 사항은 Lucid의 가격 페이지를 확인하세요)
- 네트워크 왕복으로 인해 로컬 백엔드보다 지연 시간이 높습니다 (일반적으로 쿼리당 50--200ms)
- 자체 호스팅 Lucid 배포는 별도 라이선스가 필요합니다
문제 해결
"Authentication failed" 오류
- API 키가 올바르고 Lucid 대시보드에서 취소되지 않았는지 확인합니다
- API 키에 "Memory Read/Write" 권한이 있는지 확인합니다
base_url이 올바른 Lucid 엔드포인트를 가리키는지 확인합니다
메모리 리콜에서 결과가 반환되지 않음
- Lucid 대시보드에서 메모리가 저장되었는지 확인합니다
similarity_threshold를 낮추어 (예:0.3) 결과가 필터링되는지 확인합니다workspace_id가 메모리가 저장된 워크스페이스와 일치하는지 확인합니다
리콜 쿼리의 높은 지연 시간
top_k를 줄여 쿼리당 반환되는 결과를 줄입니다- Lucid API 엔드포인트와의 네트워크 지연 시간을 확인합니다
- Lucid가 배포에 더 가까운 엔드포인트를 제공하는 경우 지역
base_url사용을 고려합니다
세션 간 메모리가 유지되지 않음
[memory]섹션에backend = "lucid"가 설정되어 있는지 확인합니다- 모든 에이전트 인스턴스에서
workspace_id가 일관된지 확인합니다 - 지속성 실패를 나타낼 수 있는 쓰기 오류에 대해 PRX 로그를 확인합니다
관련 페이지
- 메모리 시스템 개요
- SQLite 백엔드 -- 로컬 단일 파일 대안
- PostgreSQL 백엔드 -- 자체 호스팅 다중 사용자 대안
- Embeddings 백엔드 -- 로컬 벡터 기반 시맨틱 메모리
- 메모리 정리 -- 압축 및 정리 전략