AgentDB

관계형 SQL

조인, CTE, 트랜잭션, 인덱스를 지원하는 완전한 SQL을 제공하여, 세션·사용자·로그·이벤트 같은 구조화 데이터를 에이전트 메모리와 함께 저장하고 표준 SQL로 조회할 수 있습니다.

벡터 검색 (HNSW)

Pure-Rust HNSW 인덱스를 사용해 코사인·유클리드·내적 유사도와 MongoDB 스타일 메타데이터 필터링을 지원합니다. README 기준으로 1,536차원 10만 벡터에서 약 47ms, 1만 벡터에서 약 8.7ms의 ANN 검색 시간을 안내합니다.

메모리 그래프

개념·엔터티·세션 간 관계를 가중치 있는 타입 그래프로 모델링하고 깊이 제한 순회를 제공합니다. 지식 그래프, 에이전트 메모리 네트워크, 관계 기반 검색에 활용할 수 있습니다.

전문 검색 (FTS)

Porter 스테밍과 스니펫 추출이 포함된 BM25 랭킹 기반 전문 검색을 제공하여, Elasticsearch 등 외부 서비스 없이 키워드 기반 검색을 지원합니다.

하이브리드 질의

그래프 순회와 벡터 유사도를 하나의 질의에서 alpha 매개변수로 결합하는 하이브리드 질의를 지원합니다. v0.7.0에서는 Tri-Modal 하이브리드 질의로 확장되어 벡터 ANN + 그래프 순회 + FTS BM25를 alpha/beta/gamma 가중치로 혼합할 수 있습니다.

대화 스레딩

역할·내용·메타데이터를 갖는 다중 턴 대화를 저장하고 시간순으로 조회할 수 있는 1급 시민(conversation) 기능을 제공합니다.

워크플로 영속성

다단계 에이전트 작업의 상태를 단계별 입력·출력·오류와 함께 저장하여, 재시작 후에도 중단 지점에서 정확히 재개할 수 있도록 합니다.

추론 기록(Reasoning Traces)

체인 오브 소트, 도구 호출, 의사 결정 시퀀스를 트리 구조로 기록하여 디버깅·평가·감사 용도로 재생할 수 있습니다.

동기화 엔진 (v0.7.0 신규)

Hybrid Logical Clocks와 작업 로그, Last-Writer-Wins/First-Writer-Wins 설정이 가능한 CRDT 기반 동기화 엔진을 통해 여러 AgentDB 인스턴스를 복제할 수 있습니다.

설치

Windows에서는 WinGet으로 설치합니다.

• WinGet: winget install --id Datacules.AgentDB --exact
• Python: pip install datacules-agentdb
• Node.js/TypeScript: npm install @datacules/agentdb
• Rust: cargo add datacules-agentdb

CLI 기본 사용

설치 후 .agentdb 파일을 대상으로 대화형 셸, 통계 조회, SQL 실행, 벡터 검색, 컬렉션 목록, HNSW 재구축 등을 수행할 수 있습니다. README에 안내된 주요 CLI 명령은 다음과 같습니다.

• agentdb shell my_agent.agentdb — 대화형 SQL 셸
• agentdb stats my_agent.agentdb — 데이터베이스 요약 정보
• agentdb inspect my_agent.agentdb — 통계와 컬렉션·그래프를 포함한 상세 보고서
• agentdb sql my_agent.agentdb "SELECT * FROM sessions LIMIT 10" — SQL 실행
• agentdb search my_agent.agentdb memories 0.9 0.1 0.0 --top-k 5 — Tri-Modal 가중치 기반 검색
• agentdb collections my_agent.agentdb — 벡터 컬렉션 목록
• agentdb reindex my_agent.agentdb — HNSW 인덱스 재구축
• agentdb version — 버전과 타겟 트리플 출력
• agentdb export [<table>] — SQL 덤프 출력

Python 빠른 시작 예시

README의 예시 코드를 한국어 안내와 함께 제공합니다.

• AgentDB.open("my_agent.agentdb")로 데이터베이스를 열거나 생성합니다.
• db.conversations()로 대화를 생성하고 메시지를 추가합니다.
• db.collection("memories", dim=1536)로 벡터 컬렉션을 만들고 임베딩을 저장·검색합니다.
• db.query_json("SELECT * FROM _adb_conversations")로 SQL 질의를 수행합니다.

Q. AgentDB는 서버 없이 동작하나요?

네. 단일 파일 내장 데이터베이스로 설계되어 별도의 서버, 데몬, 구성 파일 없이 동작합니다. 동기화는 선택 사항이며 네트워크 없이도 모든 핵심 기능을 사용할 수 있습니다.

Q. Windows 외 다른 운영체제에서도 사용할 수 있나요?

Python, Node.js, Rust 등 언어 패키지를 통해 Linux, macOS에서도 사용할 수 있습니다. WinGet 패키지는 Windows 전용 배포 채널입니다.

Q. 라이선스는 무엇인가요?

Unlicense로 배포되며, 이는 사실상 퍼블릭 도메인과 동등한 조건입니다. 자세한 내용은 저장소의 LICENSE 파일을 참조하시기 바랍니다.

Q. 브라우저에서도 데이터를 영구 저장할 수 있나요?

v0.7.0부터 WASM OPFS 영속 저장이 지원되어 페이지 새로 고침 이후에도 데이터베이스가 유지됩니다.