[DevOps] TencentDB Agent Memory 소개 및 사용 방법

개요

TencentDB Agent Memory는 AI 에이전트의 대화와 작업 기록을 계층형 메모리로 저장하고 다시 불러오는 오픈소스다.
긴 대화 기록을 매번 프롬프트에 넣으면 토큰 사용량이 늘고, 단순 요약만 남기면 원문 근거를 찾기 어렵다.
이 프로젝트는 짧은 작업 상태와 장기 사용자 정보를 나눠 관리하고, 상위 요약에서 원본 대화까지 내려갈 수 있는 경로를 남긴다.

메인 브랜치는 OpenClaw와 Hermes 연동을 중심으로 설명한다.
GitHub Releases에서는 v0.3.6이 Latest이며, 독립 Gateway와 SDK를 제공하는 v1.0.1은 Pre-release로 표시되어 있다.

주요 특징

장기 메모리는 네 단계로 구성된다.
L0 Conversation은 원본 대화, L1 Atom은 개별 사실, L2 Scenario는 상황별 묶음, L3 Persona는 사용자 성향과 선호를 담는다.

짧은 작업의 도구 출력은 refs/*.md에 보관한다.
중간 요약은 JSONL로 남기고, 현재 작업 상태는 Mermaid 캔버스로 압축한다.
캔버스의 node_id와 result_ref를 따라가면 원본 로그를 다시 확인할 수 있다.

기본 저장소는 SQLite + sqlite-vec다.
검색은 BM25 키워드 검색과 벡터 검색 결과를 RRF 방식으로 합친다.
L2 Scenario와 L3 Persona는 사람이 읽을 수 있는 Markdown 파일이라 잘못 저장된 기억을 직접 추적하기 쉽다.
라이선스는 MIT다.

사용이 필요한 상황

• 장시간 실행되는 에이전트에서 도구 로그가 컨텍스트를 많이 차지할 때
• 사용자의 문체, 업무 규칙, 프로젝트 배경을 세션 사이에 유지할 때
• 잘못 회상한 정보가 어떤 대화에서 만들어졌는지 확인해야 할 때
• 로컬 저장소를 사용해 메모리 데이터의 위치를 통제할 때
• 여러 에이전트가 같은 기억 서비스를 사용하도록 PoC를 진행할 때

설치 또는 시작 방법

아래 예시는 OpenClaw가 설치된 환경을 기준으로 한다.

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

~/.openclaw/openclaw.json에 플러그인을 활성화한다.

{
  "memory-tencentdb": {
    "enabled": true
  }
}

긴 도구 출력을 외부 파일로 옮기는 단기 압축은 offload.enabled를 true로 설정해야 한다.

실습

1. OpenClaw에서 같은 프로젝트를 주제로 여러 차례 대화한다.
2. 선호하는 출력 형식이나 운영 규칙을 대화 중에 명시한다.
3. 새 세션에서 이전 규칙을 적용해 달라고 요청한다.
4. ~/.openclaw/memory-tdai/ 아래의 SQLite와 Scenario, Persona 파일을 확인한다.
5. 회상 결과가 틀리면 Persona에서 Scenario와 원본 Conversation 순서로 내려가 원인을 찾는다.

L1 추출에는 워밍업과 기본 5회 주기가 있으며, Persona는 새 메모리 50개마다 생성을 시도한다.
설치 직후 한두 번의 대화만으로 장기 메모리 전체가 만들어진다고 기대하면 안 된다.

 

알아야 할 사항

원본 대화와 사용자 Persona에는 개인정보, 사내 절차, 코드 조각이 들어갈 수 있다.
기본 capture.l0l1RetentionDays 값은 0이며 자동 삭제하지 않는다는 뜻이다.
운영 환경에서는 보관 기간, 암호화, 백업, 사용자별 삭제 절차를 먼저 정해야 한다.

Gateway를 사용하면 기본 포트 8420에서 capture, search, recall API가 열린다.
기본 API 키는 설정되지 않으므로 loopback 밖으로 공개할 때는 TDAI_GATEWAY_API_KEY와 CORS 허용 목록을 함께 설정해야 한다.
원격 임베딩이나 별도 LLM API를 연결하면 메모리 원문이 외부 서비스로 전송되는 범위도 확인해야 한다.

README의 토큰 절감 수치는 OpenClaw 연속 세션 벤치마크 결과이므로 다른 환경에 그대로 적용할 수 없다.
추출과 Persona 생성에도 모델 호출이 들어가므로 저장 비용뿐 아니라 추가 토큰과 지연 시간을 측정해야 한다.

이 글의 명령은 공식 README를 기준으로 작성했으며 로컬 설치는 수행하지 않았다.
1.x Gateway와 SDK는 Pre-release 문서와 변경 사항을 별도로 확인해야 한다.

장점과 아쉬운 점

장점:

• 요약에서 원본 대화까지 내려갈 수 있어 메모리의 출처를 확인할 수 있다.
• SQLite 기본 구성으로 작은 테스트 환경을 빠르게 만들 수 있다.
• Markdown, JSONL, Mermaid를 사용해 중간 결과를 사람이 읽을 수 있다.

아쉬운 점:

• 계층별 추출과 갱신 주기를 운영 환경에 맞게 조정해야 한다.
• 장기 보관되는 대화와 Persona에 대한 개인정보 관리가 필요하다.
• 0.x 플러그인과 1.x 서비스 구조가 함께 존재해 버전 선택에 주의해야 한다.

정리

TencentDB Agent Memory는 대화 기록을 평평한 벡터 목록으로만 저장하지 않고 작업 상태, 사실, 상황, Persona로 나눠 관리한다.
긴 작업을 이어 가거나 사용자별 업무 규칙을 기억해야 하는 에이전트에 맞는다.

처음에는 로컬 SQLite와 테스트 계정으로 회상 정확도, 토큰 사용량, 삭제 절차를 확인하는 편이 안전하다.
도입 전 README, 설정 스키마, CHANGELOG, 릴리스 상태를 다시 확인해야 한다.

참고 자료

• TencentDB Agent Memory GitHub
• Releases
• CHANGELOG
• OpenClaw 설정 스키마
• 운영 도구 문서