pumaDB

pumaDB: AI 에이전트를 위한 강력한 지속성 메모리 레이어

AI 기술이 발전함에 따라 에이전트의 성능을 좌우하는 핵심 요소 중 하나는 바로 '기억력'입니다. 하지만 대다수의 AI 에이전트는 세션이 종료되면 이전의 대화나 설정값을 잊어버리는 한계가 있습니다. pumaDB는 이러한 문제를 해결하기 위해 탄생한 AI 에이전트 전용 메모리 레이어입니다. "에이전트는 잊지만, pumaDB는 기억합니다(Agents forget. pumaDB remembers)."

본 아티클에서는 별도의 데이터베이스 구축 작업 없이도 에이전트에게 지속적인 기억력을 부여할 수 있는 pumaDB의 특징과 사용 방법, 주요 기능 및 활용 사례를 심층적으로 살펴보겠습니다.

---

1. What's pumaDB?

pumaDB는 AI 에이전트가 정보를 영구적으로 저장하고 검색할 수 있도록 설계된 호스팅형 JSON 메모리 레이어입니다. 개발자는 복잡한 데이터베이스 인프라를 직접 관리할 필요 없이, 호스팅된 MCP(Model Context Protocol) 또는 서버 측 REST API를 연결하기만 하면 됩니다.

이 서비스는 에이전트가 과거의 대화 내용, 사용자의 선호도, 프로젝트의 규칙, 작업 상태 등을 JSON 행(row) 형태로 저장하고 필요할 때마다 다시 불러올 수 있게 합니다. 이를 통해 ChatGPT, Claude, Codex 등 다양한 AI 모델이 세션을 넘나들며 일관된 맥락을 유지할 수 있도록 지원합니다.

---

2. How to Use

pumaDB는 단 몇 초 만에 설정을 완료할 수 있으며, 사용 환경에 따라 두 가지 주요 연결 방식을 제공합니다.

[01] 호스팅된 MCP (Hosted MCP) 연결

AI 에이전트 클라이언트에서 직접 메모리를 작성하고 읽어야 할 때 적합한 방식입니다.

• 지원 대상: Codex, ChatGPT, Claude, OpenClaw 등 Streamable HTTP MCP를 지원하는 모든 클라이언트.
• 연결 방법:
  • OAuth 인증 또는 동적 클라이언트 등록을 지원합니다.
  • 엔드포인트 URL: https://api.pumadb.ai/mcp 를 복사하여 클라이언트에 설정합니다.

[02] 서버 측 API (Server-side API) 연결

소규모 서버 앱이나 서버리스 환경에서 안전하게 데이터를 관리할 때 사용합니다.

• 연결 방법:
  • 백엔드 환경에 puma_live_* 키를 보관합니다.
  • https://api.pumadb.ai/v1 엔드포인트를 직접 호출하여 데이터를 처리합니다.
• 주의 사항: 보안을 위해 API 키를 React 번들, 정적 사이트, 모바일 앱, 브라우저 코드 또는 공개 저장소와 같은 클라이언트 측에 노출해서는 안 됩니다.

---

3. Features (주요 기능)

pumaDB는 에이전트의 효율적인 기억 관리를 위해 다음과 같은 핵심 기능을 제공합니다.

경량 메모리 스키마

에이전트가 기억해야 할 거의 모든 종류의 소규모 JSON 레코드를 저장할 수 있습니다. 사실 관계, 상태 정보, 노트, 설정, 스크래치패드 등 미래의 도구 호출(tool call)을 더 스마트하게 만들어주는 데이터를 자유롭게 관리하세요.

강력한 안전 장치 (Safety Rails)

pumaDB는 메모리를 의도적으로 작고 명확하게 유지하며, 안전한 데이터 관리를 위한 기능을 내장하고 있습니다.

• 계정 제한: 계정당 최대 20개의 테이블, 테이블당 1,000개의 행, 총 25MB의 저장 공간을 제공합니다.
• 속도 제한 (Rate Limits): 키당 분당 30회의 쓰기 및 60회의 읽기 제한을 적용하여 안정성을 확보합니다.
• 버전 기록: 모든 업데이트 및 삭제 시 이전 행의 내용이 자동으로 아카이브됩니다. 최근 10개의 버전을 30일 동안 보관하며, 한 번의 호출로 복구가 가능합니다.
• 자연어 편집 (Natural Edits): 에이전트가 "내가 짧은 PR 요약을 선호한다는 것을 기억해줘"와 같은 평문 요청을 인식하여 중복 없이 데이터를 업데이트할 수 있도록 지원합니다.

뷰어 링크 (Viewer Links)

작은 쿼리는 인라인 JSON으로 반환되지만, 텍스트가 크거나 결과 세트가 방대할 경우 짧은 수명의 뷰어 및 다운로드 링크를 생성하여 가독성을 높입니다.

---

4. Use Case (활용 사례)

pumaDB는 다양한 시나리오에서 AI 에이전트의 지능을 극대화하는 데 사용될 수 있습니다.

• 스킬 마크다운 (Skills Markdown): 여러 세션에 걸쳐 로드할 수 있는 재사용 가능한 운영 지침, 프로젝트별 워크플로우 및 도구 관련 노트를 저장합니다.
• 프로젝트 규칙 (Project Conventions): 리포지토리 정보, 아키텍처 메모, 브랜치 규칙, 명명 규칙 등 매번 다시 설명할 필요가 없는 결정 사항들을 기록합니다.
• 사용자 선호도 (User Preferences): 대화 스타일, 포맷 기본값, 리뷰 기대치 등 사용자나 워크스페이스별로 특화된 선호도를 유지합니다.
• 연구 스크랩 (Research Clippings): 시간이 지나도 지속되는 조사 과정에서의 소스, 요약, 링크, 비교 노트 및 후속 질문들을 관리합니다.
• 작업 상태 (Task State): 실행 중인 작업의 블로커, 핸드오프 노트, 보류 중인 명령 등 장기 실행 작업의 상태 레코드를 저장합니다.
• 타입 기반 안전 메모리 (Typed Safe Memory): 리소스, 코드 스니펫, 마크다운, 명령 및 구성 예제를 비활성 레코드로 저장하여 사용 전 검토가 가능하도록 합니다.

---

5. REST AND MCP 엔드포인트 상세

pumaDB는 동일한 데이터 표면에 대해 두 가지 접근 방식을 제공합니다.

REST 엔드포인트

서버 측 코드, 워커(Workers), CLI 등에서 Bearer API 키를 사용하여 호출합니다.

• GET /v1/{table}: 테이블 데이터 조회
• POST /v1/{table}: 데이터 추가
• POST /v1/{table}/update_row: 특정 행 업데이트
• POST /v1/{table}/update_where: 조건부 업데이트
• DELETE /v1/{table}: 데이터 삭제

MCP 도구 호출 (Agent-facing)

에이전트가 OAuth 인증을 통해 직접 사용하는 도구 세트입니다.

• add, query, batch, upsert, update_row, update_where 등 지원
• list_tables, count: 메타데이터 확인
• versions, restore: 데이터 복구 및 이력 관리
• remember: 새로운 타입의 메모리 작성을 위한 통합 도구

---

6. FAQ

Q: 한 계정에서 얼마나 많은 데이터를 저장할 수 있나요? A: pumaDB는 계정당 최대 20개의 테이블을 생성할 수 있으며, 각 테이블당 1,000개의 행을 저장할 수 있습니다. 전체 저장 용량은 25MB로 제한됩니다.

Q: 실수로 데이터를 삭제하거나 잘못 업데이트하면 어떻게 하나요? A: pumaDB는 자동 버전 기록 기능을 제공합니다. 모든 업데이트와 삭제 건에 대해 최근 10개의 버전을 30일간 보관하므로, restore 기능을 통해 언제든지 복구할 수 있습니다.

Q: 어떤 AI 에이전트와 호환되나요? A: ChatGPT, Claude, Codex 등 MCP(Model Context Protocol)를 지원하거나 REST API 호출이 가능한 모든 AI 환경에서 사용할 수 있습니다.

Q: API 키를 프론트엔드 코드에 넣어도 되나요? A: 아니요. 보안을 위해 API 키는 반드시 서버 측 환경 변수에 보관해야 하며, 공개적인 클라이언트 측 코드에 포함시켜서는 안 됩니다.