TencentDB Agent Memory: AI 에이전트를 위한 계층형 로컬 기억 시스템

9bow · 7월 9, 2026, 9:30오전

TencentDB Agent Memory 소개

TencentDB Agent Memory는 AI 에이전트에게 장기 기억과 단기 기억을 완전 로컬로 제공하는 오픈소스 메모리 시스템입니다. 에이전트를 쓰다 보면 같은 SOP, 프로젝트 배경, 도구 사용 규칙, 출력 형식을 매번 다시 설명하게 되는데, 이런 정보는 반복 입력할 필요도 없고 그렇다고 컨텍스트에 무작정 쏟아부을 것도 아닙니다. 이 프로젝트는 에이전트가 사용자의 작업 방식을 학습하고 과거 맥락을 유지하도록 도와, 사람이 판단과 창작에 집중하도록 하는 것을 목표로 합니다.

가장 큰 설계 원칙은 평면적인 벡터 저장(flat storage)을 거부하고 계층화(layering)와 심볼화(symbolization)를 채택했다는 점입니다. 전통적인 메모리 시스템은 데이터를 조각으로 잘라 평면 벡터 저장소에 쌓기 때문에, 검색이 서로 연결되지 않은 조각들 사이를 헤매는 형태가 되기 쉽습니다. TencentDB Agent Memory는 장기 기억을 L0에서 L3까지의 의미 피라미드로 구성하고, 단기 기억은 Mermaid 심볼 그래프로 압축하는 두 축으로 이 문제에 접근합니다.

TencentDB Agent Memory는 Tencent가 개발한 OpenClaw·Hermes용 플러그인으로, 기본 백엔드로 SQLite + sqlite-vec 를 사용하며 외부 API 의존성 없이 로컬에서 동작합니다. 저자는 OpenClaw와 통합했을 때 토큰 사용량이 최대 61.38% 감소하고, 통과율이 상대 기준 51.52% 향상되며, PersonaMem 정확도가 48%에서 76%로 올랐다고 보고합니다(README Highlights 표 기준). 이 수치들은 고립된 단일 턴이 아니라 연속된 장기 세션에서 측정한 값이라고 명시하고 있습니다.

TencentDB Agent Memory의 계층형 메모리 구조

TencentDB Agent Memory의 장기 기억은 대화를 위에서부터 점진적으로 추상화하는 4단계 피라미드입니다. 아래는 원문에 포함된 L0에서 L3까지의 의미 피라미드 다이어그램입니다.

L0 Conversation(대화): 원본 대화와 이벤트 스트림을 그대로 보존해, 원 정보가 손실되지 않고 근거(evidence)를 제공합니다.
L1 Atom(원자 사실): 사실·선호·제약·상태를 자동으로 추출해 노이즈에서 핵심 정보를 뽑아냅니다.
L2 Scenario(장면): 프로젝트·주제·워크플로우 시나리오별로 묶어, 맥락 기반 회상으로 서로 다른 장면이 뒤섞이는 것을 줄입니다.
L3 Persona(페르소나): 사용자 선호와 서비스 스타일을 담은 안정적 프로필로, 에이전트가 사용자 습관에 맞춰 협력하도록 합니다.

핵심은 압축하되 근거를 잃지 않는다는 점입니다. 이 시스템은 되돌릴 수 없는 요약을 만들지 않고, 상위 추상에서 실제 근거로 되짚어 내려가는 결정적 경로를 유지합니다. 즉 "상위 심볼(페르소나·캔버스) → 중간 인덱스(장면·jsonl) → 하위 원문(L0 대화·refs)" 로 드릴다운(drill-down)할 수 있습니다. 하위 계층은 데이터베이스에 저장해 견고한 전문 검색을 지원하고, 상위 계층은 사람이 읽을 수 있는 Markdown 파일로 저장해 정보 밀도와 화이트박스 검사를 확보하는 이종(heterogeneous) 저장 전략을 씁니다.

TencentDB Agent Memory의 심볼릭 단기 기억

긴 작업에서 토큰을 가장 많이 소모하는 것은 검색 결과, 코드, 오류 추적 같은 장황한 중간 로그입니다. TencentDB Agent Memory는 이를 컨텍스트 오프로딩(context offloading)과 심볼릭 메모리로 처리합니다. 전체 도구 로그는 외부 파일(refs/*.md)로 내보내고, 컨텍스트에는 node_id를 가진 경량 Mermaid 캔버스만 남깁니다. 에이전트는 이 심볼 그래프 위에서 추론하다가, 세부 사항을 확인해야 할 때 node_id로 원문을 즉시 다시 불러옵니다. 저자에 따르면 이 방식은 토큰 비용을 줄이면서도 완전한 추적성을 유지합니다.

이 구조가 주는 실용적 이점 중 하나는 화이트박스 디버깅입니다. 대부분의 메모리 시스템은 회상이 틀렸을 때 벡터 점수 목록만 보여줘 어디서 문제가 생겼는지 알기 어렵습니다. TencentDB Agent Memory는 L2 장면 블록을 평문 Markdown으로, L3 페르소나를 persona.md 로, 단기 작업 캔버스를 Mermaid로 남겨, "페르소나 → 장면 → 원자 사실 → 대화" 를 따라 내려가며 원인을 추적할 수 있게 합니다. 이 계층형 산출물은 모두 ~/.openclaw/memory-tdai/ 아래에 저장되어 직접 열어 볼 수 있습니다.

검색은 BM25 키워드 검색과 벡터 검색을 RRF로 융합하는 하이브리드 방식을 기본으로 하며, tdai_memory_search 와 tdai_conversation_search 두 에이전트 도구를 제공합니다.

TencentDB Agent Memory 설치 및 사용법

OpenClaw 환경에서는 플러그인 설치와 게이트웨이 재시작만으로 시작할 수 있습니다.

openclaw plugins install @tencentdb-agent-memory/memory-tencentdb
openclaw gateway restart

이후 설정 파일에서 활성화하면 별도 구성 없이 로컬 SQLite + sqlite-vec 백엔드로 동작합니다.

// ~/.openclaw/openclaw.json
{
  "memory-tencentdb": {
    "enabled": true
  }
}

활성화되면 대화 캡처, 메모리 추출, 장면 집계, 페르소나 생성, 다음 턴 이전의 회상까지 자동으로 처리합니다. 모든 설정 항목에는 합리적인 기본값이 있어 무설정으로 실행되며, 회상 전략(recall.strategy), 회상 개수(recall.maxResults), L1 추출 주기(pipeline.everyNConversations), 페르소나 생성 주기(persona.triggerEveryN) 같은 항목을 필요에 따라 조정할 수 있습니다. OpenClaw 외에 Hermes 에이전트도 Docker 이미지 또는 기존 설치에 연결하는 방식으로 지원합니다.

Hermes 게이트웨이는 :8420 포트에서 캡처·검색·회상 HTTP 엔드포인트를 노출하는데, 기본값은 로컬 사이드카로 열려 있습니다. server.apiKey(TDAI_GATEWAY_API_KEY)를 설정하면 GET /health 를 제외한 모든 경로가 Bearer 토큰을 요구하고, server.corsOrigins 로 CORS 허용 목록을 지정할 수 있습니다. 두 옵션 모두 기존 배포가 그대로 동작하도록 기본은 꺼져 있으며, 네트워크에 노출할 때 켜는 선택적 보안 장치입니다.

TencentDB Agent Memory의 라이선스

TencentDB Agent Memory는 MIT 라이선스로 공개되어 있어 개인 및 상업적 목적으로 자유롭게 사용할 수 있습니다.

TencentDB Agent Memory npm 패키지

https://www.npmjs.com/package/@tencentdb-agent-memory/memory-tencentdb

TencentDB Agent Memory 프로젝트 GitHub 저장소

더 읽어보기

이 글은 GPT 모델로 정리한 글을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 덧글로 알려주시기를 부탁드립니다.

파이토치 한국 사용자 모임이 정리한 이 글이 유용하셨나요? 회원으로 가입하시면 주요 글들을 이메일로 보내드립니다! 텔레그램(Telegram)이나 Slack/Discord/Teams/Dooray/GoogleChat 등으로도 새 글 알림을 받으실 수 있습니다.

아래쪽에 좋아요를 눌러주시면 새로운 소식들을 정리하고 공유하는데 힘이 됩니다~