[기술검토] TencentDB Agent Memory — AI 에이전트 기억관리 엔진
계층형 장기기억(L0~L3)과 심볼릭 단기 로그 압축을 결합한 오픈소스 기억 엔진 검토. OpenClaw/Hermes 전용이지만 REST API로 Claude Code hook·멀티에이전트 하네스와 연동 가능. 개념 채택 권장, 제품 도입은 PoC 후 판단.
TencentDB Agent Memory 기술검토 보고서
📌 오픈소스 AI 에이전트 기억관리 엔진 TencentDB-Agent-Memory(v0.3.6)를 검토한 문서. 결론은 "설계 개념은 채택, 제품 도입은 PoC 후 판단" — 계층형 장기기억과 추적 가능한 로그 압축 개념은 자체 구축 멀티에이전트 하네스(이하 AI 개발 파이프라인)에 잘 맞지만, 즉시 설치해 쓰는 물건은 아니다.
대상: TencentDB-Agent-Memory (GitHub
TencentCloud/TencentDB-Agent-Memory) 버전: v0.3.6 (2026-05-28 릴리스) · 라이선스: MIT · Node.js ≥ 22.16 · ⭐ 약 5,835 / Fork 507 (2026-06-17 확인) 검토일: 2026-06-17 · 교차검증: Claude / Gemini (codex·agy는 환경 제약으로 검증 불가)
0. 한눈에 요약 (TL;DR)
- 무엇인가: AI 에이전트가 "지난 대화·작업 맥락을 잊지 않도록" 도와주는 기억(memory) 관리 엔진. 모든 대화를 통째로 쌓는 기존 방식 대신, 정보를 계층(layer)으로 정리하고 장황한 작업 로그를 압축하는 것이 핵심.
- 두 가지 무기: ① 단기 기억 압축(긴 도구 실행 로그를 외부 파일로 빼고 한 장짜리 다이어그램만 남김) ② 장기 기억 계층화(대화 → 사실 → 상황 → 사용자 프로필 4단계).
- 원래 누구를 위한 것: OpenClaw와 Hermes라는 다른 AI 에이전트 도구 전용 플러그인. Claude Code 네이티브 지원은 없음.
- 그래도 쓸 수 있는 이유: 내부에 REST API(HTTP) 게이트웨이가 있어서, Claude Code의 hook이나 AI 개발 파이프라인 백엔드가 HTTP 호출로 직접 연동할 수 있음.
- 결론: 즉시 "설치해서 끝"인 물건이 아니다. 하지만 설계 개념(계층형 기억 + 로그 압축)은 AI 개발 파이프라인이 이미 가진 데이터에 매우 잘 맞아 벤치마킹 가치가 크다. PoC(개념검증) 권장, 전면 도입은 보류.
1. 이게 대체 뭔가요? (비전공자용 설명)
AI에게 일을 시키면, AI는 "방금 나눈 대화"만 기억합니다. 어제 알려준 회사 규칙, 프로젝트 배경, 내가 선호하는 방식을 매번 다시 설명해야 합니다. 마치 매일 아침 기억이 초기화되는 직원과 같습니다.
기존 해결책은 "지난 대화를 전부 창고에 쌓아두고, 필요할 때 검색"하는 방식이었습니다. 그런데 창고가 너무 커지면 ⑴ 찾는 데 돈(토큰)이 많이 들고 ⑵ 엉뚱한 걸 꺼내옵니다.
TencentDB Agent Memory의 접근은 "도서관 사서"에 가깝습니다.
- 모든 원본 대화를 그냥 쌓아두지 않고, 중요한 것만 골라 카드로 정리합니다.
- 카드를 다시 주제별로 묶고, 최종적으로 "이 사용자는 이런 사람"이라는 한 장짜리 프로필까지 만듭니다.
- 다음 대화가 시작되기 전에, 지금 상황에 맞는 카드만 살짝 꺼내 AI에게 귀띔해 줍니다.
또 하나, AI가 긴 작업을 하면 중간 과정(검색 결과, 코드, 오류 메시지)이 어마어마하게 쌓입니다. 이걸 그대로 들고 다니면 무겁습니다. 그래서 이 도구는 긴 기록을 바깥 서랍(파일)에 넣어두고, 작업 흐름은 "한 장짜리 지도(다이어그램)"로만 들고 다닙니다. 자세한 게 필요하면 그때 서랍을 엽니다.
💡 핵심 철학(README 인용): "기억은 AI에 모든 걸 쌓아두는 것이 아니라, 사람이 같은 말을 반복하지 않게 해주는 것이다."
2. 핵심 기술 — 두 개의 축
축 A. 심볼릭 단기 기억 (Symbolic Short-term Memory)
긴 작업 중 토큰을 가장 많이 잡아먹는 "장황한 중간 로그" 문제를 푸는 방식.
| 단계 | 하는 일 | 비유 |
|---|---|---|
| 원본 보관 | 전체 도구 로그를 외부 파일 refs/*.md로 빼냄 | 서류 원본을 서랍에 보관 |
| 관계 추출 | 작업 상태 변화를 Mermaid 다이어그램(node_id 포함)으로 압축 | 서류를 한 장 흐름도로 요약 |
| 가벼운 주입 | AI 컨텍스트에는 다이어그램(수백 토큰)만 남김 | 책상엔 요약본만 올려둠 |
| 추적 복원 | 세부가 필요하면 node_id로 원본을 다시 검색 | 필요할 때 서랍에서 원본 꺼냄 |
→ 압축하되 원본 추적 가능(lossless)이 차별점. 일반적인 "요약 저장"은 원본을 잃지만, 이건 항상 원본으로 되돌아갈 길을 남겨둠.
축 B. 계층형 장기 기억 (Layered Long-term Memory)
대화를 평평한 벡터 더미에 쌓지 않고 의미 피라미드로 정리.
- 하위(L0/L1)는 "증거", 상위(L2/L3)는 "구조". 평소엔 상위만 보고, 사실 확인이 필요할 때만 하위로 내려감.
- 저장 방식이 이원화(heterogeneous): 하위 계층(사실·로그)은 SQLite + sqlite-vec DB에 넣어 전문검색, 상위 계층(페르소나·장면·캔버스)은 사람이 직접 열어볼 수 있는 Markdown 파일(
~/.openclaw/memory-tdai/)로 저장 → "화이트박스" 디버깅 가능. - 검색: BM25(키워드) + 벡터(의미) + RRF 융합의 hybrid가 기본. (
keyword/embedding/hybrid선택 가능)
3. 어디에 붙이는 물건인가 — 연동 구조
공식 지원 대상 (네이티브)
- OpenClaw 플러그인 —
openclaw plugins install @tencentdb-agent-memory/memory-tencentdb설치 후 설정에서enabled: true. 기본 백엔드 SQLite. 설치만 하면 캡처·추출·회상이 자동. - Hermes(Nous Research) Gateway 어댑터 — Docker 한 방 실행 또는 기존 Hermes에 플러그인 연결.
⚠️ Claude Code는 둘 다 아니다. 따라서 "플러그인 설치"로는 못 쓴다.
우리가 쓸 수 있는 통로 — Gateway REST API (검증 완료)
게이트웨이는 기본 포트 8420에서 다음 HTTP 엔드포인트를 노출 (src/gateway/server.ts에서 직접 확인):
| 메서드 / 경로 | 역할 | 필수 입력 |
|---|---|---|
GET /health | 헬스체크 (인증 면제) | — |
POST /recall | 다음 턴 전 관련 기억 회상(prefetch) | query, session_key |
POST /capture | 대화 턴 저장(L0→L1 추출 트리거) | user_content, assistant_content, session_key |
POST /search/memories | L1 원자 기억 검색 | query |
POST /search/conversations | L0 원본 대화 검색 | query |
POST /session/end | 세션 종료 처리 | — |
POST /seed | 초기 기억 주입 | — |
→ 이 REST API가 핵심. Claude Code의 hook(예: UserPromptSubmit, Stop/SessionEnd)이나 AI 개발 파이프라인 백엔드가 이 엔드포인트를 HTTP로 호출하면 OpenClaw/Hermes가 아니어도 연동 가능하다. 검토 과정에서 받은 의견 중 "REST API를 제공하므로 Claude Code와 연결 가능"은 사실로 확인됨.
⚠️ 중요한 한계 (교차검증으로 드러난 정확성 포인트): REST
/capture·/recall은 장기 기억(L0~L3) 파이프라인용이다. 단기 로그 압축(축 A, Mermaid offload) 기능은 OpenClaw의contextEngine슬롯 등록 + 런타임 패치 스크립트에 묶여 있어, REST API만으로는 그대로 가져오기 어렵다. 즉 외부 하네스(Claude Code)에서는 "장기 계층 기억"은 API로 붙이기 쉽고, "단기 심볼릭 압축"은 개념만 차용하는 편이 현실적이다.
4. 검증된 사실 vs. 주의할 점
✅ 공식 확인 사실
- 버전 v0.3.6, MIT, Node ≥ 22.16, 기본 백엔드 로컬 SQLite+sqlite-vec. (package.json / README)
- 저장 산출물은
~/.openclaw/memory-tdai/아래에 사람이 읽을 수 있게 적재 → 화이트박스. - 게이트웨이 보안: 기본은 localhost 사이드카.
TDAI_GATEWAY_API_KEY설정 시/health제외 전 라우트에 Bearer 토큰 인증(상수시간 비교), 비루프백(0.0.0.0) 바인딩 시 경고 출력, CORS 기본 빈 리스트(브라우저 교차요청 차단).
⚠️ 반드시 짚을 주의사항
- 벤치마크는 전부 "자체 측정값" — WideSearch 성공률 33→50%·토큰 −61.38%, SWE-bench 58.4→64.2%, PersonaMem 정확도 48→76% 등은 프로젝트 자체 실험치이고 제3자 검증·재현 스크립트는 미확인. 자기 워크로드로 직접 재현 검증 필수. (특히 토큰 −61% 절감은 "장황한 로그가 많은 극단적 케이스" 기준일 가능성 높음 — Gemini 지적)
- "외부 통신 없음"은 조건부 — 로컬 SQLite로 시작은 가능하나, L1/L2/L3 추출·임베딩에 OpenAI 호환 LLM/embedding API를 설정하면 외부 통신이 발생한다. 기본은 off지만 모델 구성에 따라 켜진다. → 내부 데이터가 외부 LLM으로 나갈 수 있는 구간이므로 도입 전 반드시 점검. (검토 과정에서 받은 "설정에 따라 외부 통신 구간 활성화" 경고는 정확)
- 설치 안정성 —
postinstall이 OpenClaw 런타임을 수정하는 패치 스크립트를 실행. Windows PowerShell 설치 실패 이슈, semver 범위로 인한 플러그인 비활성화 이력 등 초기(0.3.x) 단계 리스크 존재. 어떤 파일을 건드리는지 사전 검토 권장. - 버전 초기 단계 — 0.3.x. 로드맵상 "크로스 에이전트 이식", "자동 Skill 생성", "메모리 관측 대시보드"는 아직 미완(
[ ]).
5. AI 개발 파이프라인 / Claude Code 활용 방안
AI 개발 파이프라인(자체 구축 멀티에이전트 하네스)은 이미 Claude Code 세션·이벤트·도구 로그·에이전트 트리를 PostgreSQL에 수집하고, MCP로 지식베이스 검색·작업 로그 조회·이벤트 검색 도구를 제공한다. TencentDB의 개념은 파이프라인이 이미 가진 데이터를 "지식"으로 승격시키는 방향과 정확히 일치한다.
방안 1. 개념 차용 — 파이프라인 자체 "계층형 기억" 레이어 (권장도 ★★★)
TencentDB를 설치하지 않고 L0→L3 계층화 아이디어만 파이프라인에 이식.
- 파이프라인이 이미 저장하는 세션 이벤트(L0) → 백그라운드 collector가 핵심 사실(L1) 추출 → 반복 패턴을 **시나리오(L2)**로, 사용자/프로젝트 규칙을 **페르소나(L3)**로 정리.
- 저장은 이미 쓰는 PostgreSQL(하위 계층) + Markdown 산출물(상위, 화이트박스)로 이원화 — TencentDB 설계 그대로.
- 외부 의존·외부 통신 0. 가장 안전하고 기존 3-Layer 아키텍처에 자연스럽게 안착.
방안 2. REST API 직접 연동 — Claude Code hook ↔ Gateway (권장도 ★★☆, PoC용)
TencentDB Gateway를 로컬 사이드카로 띄우고 Claude Code hook이 호출.
UserPromptSubmithook →POST /recall {query, session_key}결과를 프롬프트 머리에 주입(과거 해결 패턴·규칙 회상).Stop/SessionEndhook →POST /capture또는POST /session/end로 턴 저장.- 반드시
TDAI_GATEWAY_API_KEY설정 + 루프백(127.0.0.1) 바인딩 + 임베딩/LLM은 내부 엔드포인트로 제한해 외부 통신 차단. - 장점: 빠른 PoC로 "토큰 절감/회상 정확도"를 자기 데이터로 직접 측정 가능. 단점: 외부 의존 추가, 단기 압축(Mermaid)은 이 경로로 안 옴.
방안 3. 파이프라인 ↔ Gateway "지식 동기화 워커" (권장도 ★★☆)
파이프라인 백엔드에 Sync Worker를 추가해 수집된 도구 로그를 Gateway로 전달(/capture//seed), 생성된 기억을 파이프라인이 시각화(Mermaid 캔버스/페르소나 뷰).
- 역할 분담: 파이프라인 = 현황 대시보드 + 시각화, TencentDB = 지식화 엔진. (Gemini도 동일 제안)
- 방안 1과 결합 시 가장 강력하나 운영 복잡도 ↑.
방안 4. "심볼릭 로그 압축" 개념만 — 도구 로그 뷰 개선 (권장도 ★★★, 저비용)
TencentDB의 축 A(긴 로그 → 외부 파일 + Mermaid 한 장)는 파이프라인 대시보드의 tool log 표시 UX 문제와 똑같다.
- 긴 도구 출력은 접고, 세션 흐름을 Mermaid 작업 맵 + node_id 링크로 요약 표시 → 클릭 시 원본 로그 펼침.
- 외부 의존 0, 즉시 사용자 가치(대시보드 가독성·토큰 인식 개선).
권고 조합
- 단기(저비용·저위험): 방안 1 + 방안 4 — 개념만 차용, 외부 통신 없음, 파이프라인에 직접 내재화.
- 검증(중기): 방안 2로 내부 폐쇄망 PoC를 돌려 자기 워크로드 기준 실제 토큰 절감률·회상 정확도·오탐 저장률을 측정한 뒤, 수치가 좋으면 방안 3로 확장.
6. 도입 판단
| 항목 | 평가 |
|---|---|
| 설계/개념 | ★★★★★ 계층형 기억 + 추적 가능한 로그 압축은 기존 파이프라인과 궁합 우수 |
| 즉시 적용성(Claude Code) | ★★☆☆☆ 네이티브 미지원, REST 우회 필요, 단기 압축은 개념 차용만 |
| 성숙도 | ★★★☆☆ 0.3.x 초기, 설치 안정성 이슈, 벤치마크 자체측정 |
| 보안/데이터 거버넌스 | ★★★☆☆ 인증·로컬화 옵션 있으나 외부 LLM 통신 구간 점검 필수 |
결론: "개념은 채택, 제품은 PoC." 내부 폐쇄망에서 방안 1·4(개념 내재화)부터 시작하고, 방안 2로 수치를 검증한 뒤 전면 도입 여부를 결정한다. 도입 시 외부 통신 차단 + Bearer 인증 + 자체 재현 벤치마크는 비협상 전제 조건.
7. 교차검증 결과 (claude / gemini / codex / agy)
| CLI | 상태 | 결과 |
|---|---|---|
| Claude | ✅ | 본 보고서 작성·공식 소스(README/server.ts/package.json/GitHub API) 직접 대조 |
| Gemini | ✅ | 핵심 사실 정확 확인. 보완점 제시: ①hybrid 검색에 최신성(recency) 가중 가능성(※README엔 명시 없음 — 미검증), ②/capture로 단기 압축 효과를 보려면 tool_calls/outputs 구조화 필요(→ 본문 3장 한계로 반영), ③벤치마크 −61%는 극단 케이스 기준일 수 있음, ④macOS에서 sqlite-vec 빌드 호환성 점검(추측). Claude Code 적용안은 본 보고서와 일치 |
| Codex | ❌ | ChatGPT 계정에서 모델(gpt-5.3-codex) 미지원으로 거부 — 검증 불가 |
| agy | ❌ | 응답 없음(헤드리스 환경 제약) — 검증 불가 |
💡 Gemini가 제시한 "recency 가중"은 공식 README에서 확인되지 않아 미검증 항목으로 분류(환각 가능성 배제 차원). 그 외 Gemini 보완점은 본문에 반영함.
8. 출처 (공식)
- GitHub:
https://github.com/TencentCloud/TencentDB-Agent-Memory(README.md,src/gateway/server.ts,package.json직접 확인) - npm:
@tencentdb-agent-memory/memory-tencentdbv0.3.6 - GitHub API 메타데이터(2026-06-17): ⭐5,835 / Fork 507 / 최신 릴리스 v0.3.6(2026-05-28) / 미아카이브
댓글
아직 댓글이 없어요. 첫 댓글을 남겨보세요!
★이 강의 후기
후기 남기기아직 이 강의에 대한 후기가 없어요.