TencentDB Agent Memory 사용 가이드(2026 최신판)

마지막 업데이트: 2026년 8월 6일. 설치 명령과 설정 필드는 TencentDB-Agent-Memory 공식 저장소, npm 플러그인 문서, Tencent Cloud Memory 연결 준비 기준으로 검증했습니다.

OpenClaw, Hermes, 자체 프레임워크로 AI Agent를 붙여 본 적이 있다면 이런 상황을 겪었을 겁니다. 세 번째 대화에서 아까 정한 Swift 코딩 스타일을 잊는다. 스무 번의 도구 호출 뒤 컨텍스트가 터지면서 없는 경로를 지어낸다. 세션을 바꾸면 매번 프로젝트 배경을 처음부터 설명해야 한다.

예전 방식은 「대화 전체를 벡터 DB에 넣기」나 「대충 요약하기」였습니다. Tencent가 2026년 MIT로 공개한 TencentDB Agent Memory는 다른 길을 택합니다. 기호화된 단기 기억 + 4계층 장기 기억(L0–L3)을 결합하고, 기본값은 로컬 SQLite + sqlite-vec라 클라우드 없이도 돌아갑니다. 이 글은 iOS / Flutter / AI 개발자를 대상으로 「원리 이해 → 플러그인 설치 → 로컬 vs 클라우드 결정」 순서로 쓰며, Gateway를 클라우드 Mac에 7×24 상주시킬 타이밍도 짚습니다.

서론: Agent가 왜 자꾸 「잊는」가

장시간 Agent 작업이 실패하는 이유는 모델이 멍청해서가 아니라 컨텍스트 관리가 무너지기 때문인 경우가 많습니다. Wide Search나 SWE-bench 스타일 작업에서는 도구가 돌려주는 JSON, 웹 본문, 빌드 로그만 해도 수십만 토큰이 쌓입니다. 원문을 전부 창에 남기면 비용과 지연이 폭발하고, 무작정 지우면 다음 단계에서 같은 검색을 반복하거나 잘못된 파일을 고칩니다.

TencentDB Agent Memory가 풀려는 모순이 바로 이겁니다. 기억해야 할 것은 기억하되, 증거 사슬은 아래 계층에 완전히 보존합니다. OpenClaw 플러그인 공개 벤치마크에서는 단기 기억 작업에서 최대 약 61% 토큰 절감, PersonaMem 장기 기억 정확도가 48%에서 76%로 올라갔습니다. 수치는 모델과 태스크마다 다르지만, 계층 + 오프로드가 벡터 평탄화보다 비용·안정성 면에서 유리하다는 방향은 분명합니다.

Kvmkit 독자에게 흔한 워크플로는 두 가지입니다. ① Mac에서 Cursor / Claude Code에 OpenClaw 플러그인을 붙여 프로젝트 단위 기억을 쓰는 경우. ② Windows에서 Flutter를 쓰고, 클라우드 Mac에서 Gateway와 로컬 MLX 추론을 돌려 「기억 서비스」와 「Xcode 빌드」를 같은 안정 노드에 두는 경우입니다.

사내에서 Agent 파일럿을 돌리는 팀이라면 실패 로그를 보면 「모델이 약하다」보다 「컨텍스트가 깨졌다」가 더 자주 보입니다. iOS CI나 MCP 연동처럼 도구 체인이 길수록 한 번의 오류가 이후 태스크 전체를 오염시킵니다. 기억 계층을 먼저 정리하는 것은 모델 선정보다 앞서 할 가치가 있는 투자입니다.

핵심 개념: 계층형 기억과 기호화 단기 압축

이 프로젝트는 「모든 기억 조각을 벡터로 평탄하게 쌓는」 설계를 거부합니다. 장기 쪽은 의미 피라미드, 단기 쪽은 Mermaid 작업 캔버스—둘 다 점진적 공개를 씁니다. 컨텍스트에는 상위 구조만 넣고, 필요할 때 인덱스로 아래로 내려갑니다.

장기 기억 4계층(L0 → L3)

• L0 Conversation: 원본 대화와 도구 궤적. 잃으면 안 되는 증거 원본;
• L1 Atom: 대화에서 뽑은 구조화 사실(날짜, 선호, 기술 스택);
• L2 Scenario: 여러 Atom을 묶은 시나리오 블록(예: 「iOS CI 서명 플로우」);
• L3 Persona: 시나리오를 넘는 사용자 프로필. 읽기 쉬운 persona.md로 저장해 다음 라운드 전에 회상.

회상은 기본적으로 Persona / Scenario를 먼저 읽고, 필요 시 Atom이나 L0 원문으로 내려갑니다. 사람이 「이 동료는 SwiftUI를 선호한다」고 떠올린 뒤 채팅을 뒤져 확인하는 흐름과 비슷합니다.

단기 기억: Mermaid 오프로드

도구 로그는 refs/*.md로 빼고, 컨텍스트에는 node_id가 붙은 Mermaid 그래프만 남깁니다. Agent는 가벼운 기호로 추론하고, 노드가 수상하면 node_id로 원문을 grep해 100% 추적 가능하게 합니다. 로그 전문을 다시 창에 넣을 필요가 없습니다.

MCP 도구 체인을 같이 구축 중이라면, 기억 플러그인과 GitHub MCP Server 배포 가이드(Windows·Linux·macOS)를 같은 OpenClaw 설정에 올리면 정리가 쉽습니다. 도구는 「무엇을 할 수 있는지」, Memory는 「무엇을 했는지·사용자가 누구인지」를 담당합니다.

벡터 RAG만 쓰는 설계와 비교하면 감사·디버깅이 훨씬 수월합니다. 「왜 그 결론에 도달했는지」를 L0까지 거슬러 올라갈 수 있어, 프로덕션 장애 재현에도 도움이 됩니다. Flutter 팀이 위젯 트리 상태 전이를 로그로 추적하는 느낌에 가깝습니다.

실습: OpenClaw 플러그인과 Gateway 배포

가장 빠른 경로는 OpenClaw 플러그인(Node.js ≥ 22.16 필요)입니다. 아래는 macOS / Linux 터미널 기준입니다. Windows는 WSL2를 쓰거나 Gateway를 클라우드 Mac에 두는 편이 현실적입니다.

방안 A: OpenClaw 제로 설정(입문 추천)

# 플러그인 설치
openclaw plugins install @tencentdb-agent-memory/memory-tencentdb
openclaw gateway restart

~/.openclaw/openclaw.json에서 활성화:

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

기본 백엔드는 로컬 SQLite입니다. 플러그인이 대화 기록, 기억 추출, 시나리오 정리, 페르소나 생성, 다음 라운드 회상을 자동 처리합니다. 업그레이드는 openclaw plugins update @tencentdb-agent-memory/memory-tencentdb를 쓰고, 시맨틱 버전 범위 때문에 플러그인이 비활성화되지 않게 주의하세요.

단기 압축 활성화(≥ 0.3.4)

설정에서 offload를 켜고 contextEngine 슬롯을 등록합니다.

{
  "memory-tencentdb": {
    "config": {
      "offload": { "enabled": true }
    }
  },
  "plugins": {
    "slots": {
      "contextEngine": "memory-tencentdb"
    }
  }
}

저장소의 scripts/openclaw-after-tool-call-messages.patch.sh를 실행하세요(OpenClaw 업데이트 후 재실행 권장). 도구 호출 결과가 제대로 오프로드·역추적되려면 이 패치가 필요합니다. 「플러그인은 깔았는데 토큰이 안 줄어든다」는 경우의 흔한 원인입니다.

방안 B: Hermes Docker 일체형

Hermes Agent 사용자는 기억이 포함된 컨테이너를 한 줄로 띄울 수 있습니다(Gateway 8420 포트).

cd TencentDB-Agent-Memory/docker/opensource
docker build -f Dockerfile.hermes -t hermes-memory .
docker run -d --name hermes-memory -p 8420:8420 \
  -e MODEL_API_KEY="your-api-key" \
  -v hermes_data:/opt/data hermes-memory
curl http://localhost:8420/health

헬스 체크가 {"status":"ok"} 또는 degraded이면 계속 진행하면 됩니다. 이미지에 DeepSeek-V3.2 기본 엔드포인트가 내장되어 있어, 해당 모델이면 API Key만 넘겨도 되는 경우가 많습니다.

방안 C: 자체 Agent + Python SDK(클라우드)

팀 기억을 Tencent Cloud 관리형에 올릴 때는 콘솔에서 Memory를 만든 뒤 SDK를 설치합니다.

pip install tencentdb-agent-memory-sdk

비동기 클라이언트로 세션을 쓰고 Atom을 검색합니다(필드는 콘솔 스펙 따름). Python 오케스트레이션이 있고 여러 Agent가 공유 저장소를 쓰는 엔터프라이즈에 맞습니다. 개인 시험용으로 클라우드는 필수가 아닙니다.

수용 체크리스트

• 3라운드 대화 후 persona.md나 시나리오 파일이 생성되는지;
• offload 활성화 후 동일 SWE 태스크 전후 토큰 곡선 비교;
• 의도적으로 오래된 도구 결과를 참조하게 해 node_id로 refs/ 원문을 되찾는지;
• Tool Calls가 루프하면 기억 탓하지 말고 Kimi K3 도구 호출 순환: 2026년 중단 가이드로 메시지 체인을 점검.

클라우드 Mac / Apple Silicon 연계

Memory Gateway는 상시 서비스입니다. 포트 대기, 로컬 SQLite 읽기·쓰기, 백그라운드 추출·회상이 계속 돌아갑니다. 노트북 뚜껑을 닫거나 Windows 업데이트로 재부팅되면 Agent 입장에서는 「갑자기 기억 상실」입니다. iOS 팀에 현실적인 구성은 다음과 같습니다.

• 로컬: Cursor / Xcode로 코드 작성;
• 클라우드 Mac mini: OpenClaw Gateway + TencentDB Memory + Ollama/MLX를 같은 머신에;
• 원격: SSH나 화면 공유로 디버깅, 데이터 볼륨은 클라우드 디스크에 영속화.

Apple Silicon의 강점은 통합 메모리와 네이티브 Unix 환경입니다. Node 22, Docker Desktop, Homebrew 경로가 명확하고, Gateway를 오래 돌려도 데스크톱급 GPU보다 전력이 낮습니다. M4 Mac mini 대기 전력은 수 와트 수준이라 팀 공유 기억 노드에 잘 맞습니다. 로컬 GPU로 소형 모델을 돌리는 방안을 검토 중이라면, 대형 추론은 Windows에 두고 7×24 온라인이 필요한 기억과 macOS 툴체인만 Kvmkit 클라우드 Mac으로 옮기면, 집 PC 슬립으로 세션이 끊기는 위험을 줄일 수 있습니다.

원격 Mac을 쓸 때는 데이터 볼륨 백업 정책도 미리 정하세요. SQLite와 refs/는 디스크 파일이라 스냅샷이나 정기 export를 넣으면 노드 이전 시 고통이 크게 줄어듭니다. iOS 팀이 팀 iOS CI/CD: Xcode Cloud와 원격 Mac 빌드 선택 가이드에서 빌드 노드를 분리하는 것과 같은 맥락입니다.

비용·성능·리스크 비교

판단은 간단히 기억하세요. 프로토타입은 로컬 SQLite로 제로 인프라 검증. 기억 데이터가 팀 자산이 되면 상시 클라우드 Mac이나 Tencent 인스턴스로. 노트북에서 2주간 프로덕션 Agent를 돌린 뒤 이전하면 L0 대화와 refs 이전 비용을 과소평가하기 쉽습니다.

자주 묻는 질문

요약

• TencentDB Agent Memory는 L0–L3 계층 + Mermaid 오프로드로 장시간 Agent의 컨텍스트 팽창을 줄이며, 기본은 로컬에서 완결.
• OpenClaw 플러그인이 가장 빠른 입문. Hermes는 Docker, 기업 자체 구축은 Python SDK로 클라우드.
• 기억과 macOS 툴체인을 7×24 같은 머신에 두려면 슬립하는 노트북보다 클라우드 Mac mini가 안정적.

Agent 기억은 「벡터 몇 개 더 넣기」로 해결되지 않습니다. 먼저 계층 모델을 돌려 보고, 데이터를 로컬 SQLite에 둘지 팀 노드로 옮길지 결정하세요. 이 단계를 맞추면 이후 iOS CI, MCP 도구, 더 큰 모델 연결이 훨씬 수월해집니다.