smaramwbc/statewave

Statewave – AI 에이전트를 위한 결정론적이고 증거가 풍부한 메모리

무엇인가요 – Statewave는 LLM 기반 애플리케이션 옆에 위치하는 오픈소스 런타임으로, 내구성 있고 구조화된 메모리를 제공합니다. 원시적인 에피소드 (예: 채팅 메시지, Git 이벤트, Slack 게시물)를 기록하고, 히ュ리스틱 또는 LLM 컴파일러를 통해 유형화된 메모리로 컴파일한 후, 토큰 제한이 있으며, 순위가 매겨진, 결정론적(동일한 시점에 동일한 쿼리를 실행하면 항상 동일한 바이트를 반환)인 컨텍스트 번들을 제공합니다. PostgreSQL + pgvector 기반으로 구축되어 있으며, 정책 기반 라벨링, 멀티테넌트 격리, Python 및 TypeScript용 SDK를 제공합니다.

왜 중요한가요 – 대부분의 LLM 기반 봇은 상태 없음입니다. 각 요청은 빈 프롬프트에서 시작하므로, 사용자 선호사항, 과거 결정, 사용자 기록을 잊어버립니다. Statewave는 다음을 통해 이를 해결합니다:

• PostgreSQL에 이벤트를 지속화 (pgvector 확장 기능을 사용하여 임베딩 처리).
• 주제 변경 시 한 번만 컴파일하여 실시간 검색의 노이즈를 제거.
• 증거를 제공하여 컨텍스트의 각 부분이 원본 에피소드로 추적 가능.
• CPU만으로 작동 (LLM 또는 임베딩 호출은 선택 사항), 호스팅 비용이 저렴합니다.

핵심 개념

개념	역할
에피소드	추가 전용 원시 이벤트 (예: 채팅 메시지, Git PR).
메모리	컴파일러 (히ュ리스틱 정규식 또는 LiteLLM를 통한 LLM)에 의해 생성된 유형화된 요약.
컨텍스트 번들	토큰 예산에 맞춰 자르고 순위가 매겨진 메모리 목록으로, 프롬프트에 삽입 가능.
주제	메모리가 속한 논리적 엔티티 – 사용자, 리포지토리, 계정 등.
수령증	변경 불가능한 ULID 주소 기반 기록. 어떤 메모리가 번들에 포함되었는지 기록하고 HMAC-SHA256로 서명.
정책 엔진	YAML 규칙 (deny, redact, log_only)을 메모리 태그 (pii, financial, ...)에 적용.

사용 방법

from statewave import StatewaveClient

with StatewaveClient("http://localhost:8100") as sw:
    # 1️⃣ 원시 이벤트 인제스트
    sw.create_episode(
        subject_id="user-42",
        source="chat",
        type="message",
        payload={"text": "Alice asked about pricing tiers"},
    )
    # 2️⃣ 해당 주제의 메모리 컴파일 (idempotent)
    sw.compile_memories("user-42")
    # 3️⃣ 작업용 결정론적 컨텍스트 번들 가져오기
    bundle = sw.get_context(
        "user-42", task="answer pricing", max_tokens=1000
    )
    print(bundle.assembled_context)

이 루프는 인제스트 → 컴파일 → 가져오기입니다. 서버는 단일 Docker 명령어 또는 제공된 npx @statewavedev/statewave 설치 프로그램으로 시작할 수 있습니다.

주요 기능

• 결정론적 컴파일 번들 – 쿼리 시점 검색에서 발생하는 샘플링 노이즈 없음.
• 증거 및 수령증 – 모든 토큰이 원본 에피소드로 추적 가능. 수령증은 서명되어 재실행 가능.
• 플러그인 가능한 컴파일러 – 간단한 정규식 기반 히ュ리스틱 또는 LiteLLM에서 지원하는 모든 LLM (OpenAI, Anthropic, Azure, Ollama 등).
• 민감도 라벨링 및 정책 엔진 – PII, 비밀번호 등 태그가 지정된 메모리에 대해 deny, redact, log_only를 선언적으로 제어하는 YAML 규칙.
• 멀티테넌트 격리 – X-Tenant-ID 헤더로 데이터 스코프 지정. 선택적 리전 핀으로 거주지 준수 강제.
• PostgreSQL + pgvector 기반의 자가 호스팅 – 벤더 종속성 없음. 모든 클라우드 또는 온프레미스 인프라에서 작동.
• SDKs – Python (statewave-py) 및 TypeScript (statewave-ts) 클라이언트, REST OpenAPI 사양 제공.
• 커넥터 생태계 – GitHub, Slack, Gmail, Notion 등 별도 패키지로 실제 세계 이벤트를 에피소드로 Statewave에 푸시.

일반적인 사용 사례

• 사용자의 과거 티켓과 선호사항을 기억하는 고객 지원 봇.
• 세션 간 프로젝트 결정을 유지하는 장기적인 코딩 어시스턴트.
• 상태 없는 LLM과 메모리 증강 컨텍스트를 가진 동일한 LLM의 A/B 비교.
• 컴플라이언스를 위해 감사 가능한 토큰 수준 추적성이 필요한 기업용 에이전트.

시작하기

1. 서버 설치 (Docker Compose 또는 원라인 설치 프로그램).
2. 최소한의 .env 설정 – 적어도 STATEWAVE_DATABASE_URL 필요.
3. STATEWAVE_LITELLM_API_KEY와 모델 ID를 제공하여 LLM 컴파일러를 선택적으로 활성화.
4. Python 또는 TypeScript SDK를 사용해 에피소드를 인제스트하고 컨텍스트를 요청.

더 알아보기

• 전체 문서: https://github.com/smaramwbc/statewave-docs
• API 참조: http://localhost:8100/docs
• 예제 프로젝트: https://github.com/smaramwbc/statewave-examples
• 커넥터 리포지토리: https://github.com/smaramwbc/statewave-connectors

---

TL;DR – Statewave는 LLM 에이전트를 위한 자가 호스팅형, PostgreSQL 기반 메모리 계층으로, 결정론적이고 증거가 풍부한 컨텍스트, 정책 기반 라벨링, 멀티테넌트 격리를 간단한 REST API와 언어별 SDK를 통해 제공합니다.