TencentDB Agent Memory 빠른 시작: 10분 만에 AI 장기 기억 구축

Agent와 대화하다 보면 방금 합의한 네이밍 규칙을 또 묻는 경우가 많습니다. 도구 호출 로그가 컨텍스트를 가득 채우고 Token 청구서만 커지는데, 작업 통과율은 오히려 떨어지죠. 2026년 5월 Tencent는 TencentDB Agent Memory(MIT 라이선스)를 오픈소스로 공개했습니다. 기호화 단기 기억과 4계층 장기 기억을 결합한 로컬 우선 메모리 엔진으로, 기본적으로 SQLite + sqlite-vec 위에서 동작하며 외부 API에 의존하지 않습니다.

Kvmjet 독자인 iOS·Flutter·AI 앱 개발자에게 이는 실질적인 변화입니다. OpenClaw에 플러그인 하나를 더하면 약 10분 안에 Coding Agent가 프로젝트 SOP, 사용자 선호, 세션을 넘는 맥락을 기억하게 만들 수 있습니다. 벡터 DB를 직접 구축하거나 매번 프롬프트에 대화 전체를 넣을 필요가 없습니다. 이 글은 원리 설명 → 복사 가능한 명령 → Cloud Mac / Apple Silicon 병행 운영까지, 실제로 손대 볼 수 있는 기준으로 썼습니다.

핵심 결론: Agent에 부족한 것은 더 큰 context window가 아니라 계층화되고 출처를 추적할 수 있는 기억입니다. 공식 벤치마크에서 WideSearch 초장 세션 통과율이 33%에서 50%로 오르고 Token 소비는 약 61% 줄었습니다. 다단계 Agent 호출이 잦은 환경에서는 모델만 키우는 것보다 비용 대비 효과가 큰 편입니다.

1. Agent에 계층형 기억이 필요한 이유 — 컨텍스트만 늘리면 안 되는 이유

장시간 돌아가는 Agent가 실패하는 대표 패턴은 모델이 부족해서가 아니라 무관한 정보가 컨텍스트를 잠식하는 경우입니다. grep이 수천 줄을 반환하거나, 브라우저 수집 JSON이 쌓이거나, SWE-bench 하위 작업 수십 개가 한 세션에 겹치면 — 노이즈만 남고 의사결정 신호는 창 가장자리로 밀려납니다.

흔한 대응은 세 가지인데, 각각 뚜렷한 한계가 있습니다.

• 강제 잘라내기: 초기 메시지를 버립니다. 빠르지만 되돌릴 수 없고, 사용자 설정과 장애 원인이 함께 사라집니다.
• 전체 요약: LLM으로 압축합니다. Token은 줄지만 요약 환각이 생기기 쉽고 원문을 대조하기 어렵습니다.
• 평면 벡터 RAG: 대화를 잘라 embedding 검색합니다. 사용자 프로필 → 시나리오 → 원자적 사실의 계층이 없어 포스트잇 더미를 뒤지는 느낌이 납니다.

TencentDB Agent Memory는 네 번째 길을 택합니다. 계층화 + 기호화 + 드릴다운 추적입니다. 단기 작업은 Mermaid 상태 캔버스로 표현하고, 무거운 로그는 refs/*.md로 오프로드합니다. 세션을 넘는 지식은 L0 Conversation → L1 Atom → L2 Scenario → L3 Persona로 정제되며, 각 계층은 node_id로 하위 원문을 가리킵니다. 공식 문서는 이를 「점진적 공개(progressive disclosure)」라 부릅니다 — 평소엔 상위 구조만 보여 주고, 증거가 필요할 때만 파고듭니다. 자세한 내용은 Tencent Cloud Agent Memory 제품 소개를 참고하세요.

모바일·AI 제품 팀의 일상 과제와 바로 맞닿습니다. Code Review Agent는 팀 Swift 스타일 가이드를 기억해야 하고, 고객 지원 Bot은 대형 고객의 지난 불만을 떠올려야 하며, 내부 운영 Agent는 「staging에서 kubectl delete 금지」를 매 세션 설명하면 안 됩니다. 이런 내용은 매번 처음부터 말할 필요도, 되돌릴 수 없는 요약으로 지울 필요도 없습니다.

2. 핵심 개념: 단기 오프로드와 L0–L3 장기 피라미드

2.1 기호화 단기 기억(Context Offload)

도구 호출 결과는 Token 블랙홀입니다. TencentDB Agent Memory는 오프로드 + 기호화 전략을 씁니다. 전체 로그는 외부 파일 시스템에 쓰고, 컨텍스트에는 node_id가 붙은 Mermaid 작업 그래프만 남깁니다. Agent는 그래프로 추론하고, 특정 단계가 의심스러우면 node_id로 refs/ 아래 원문을 grep할 수 있습니다. 100% 추적 가능하며, 검은 상자 요약이 아닙니다.

이 기능은 플러그인 ≥ 0.3.4에서 선택적으로 켤 수 있으며, OpenClaw contextEngine 슬롯 등록과 공식 patch 스크립트 실행이 필요합니다. 공식 WideSearch 벤치마크는 통과율 +51.52%, Token −61.38%를 보고합니다.

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

장기 측은 평면 벡터 더미가 아니라 의미 피라미드입니다.

• L0 Conversation: 원본 대화와 도구 궤적. 증거 계층입니다.
• L1 Atom: 구조화된 사실(예: 「사용자는 Tab 들여쓰기 4칸 선호」).
• L2 Scenario: 시나리오 묶음(예: 「Flutter 릴리스 전 체크리스트」).
• L3 Persona: 사용자/프로젝트 페르소나. 일상 recall은 이 계층을 우선합니다.

검색은 BM25 + 벡터 + RRF 하이브리드로, 순수 의미 검색만으로 놓치는 키워드를 잡습니다. 엔터프라이즈는 Tencent Cloud Vector Database(TCVDB) 백엔드를 고를 수 있지만 PoC에는 로컬 SQLite로 충분합니다. 아키텍처와 API는 GitHub 저장소 README가 기준입니다.

2.3 연동 경로 한눈에

현재 주요 경로는 두 가지입니다.

• OpenClaw 플러그인: @tencentdb-agent-memory/memory-tencentdb, Node.js ≥ 22.16, 한 줄 설치.
• Hermes Gateway: Docker 이미지 또는 플러그인 디렉터리 마운트. 기존 Hermes 오케스트레이션 팀용.

Kvmjet 환경에서 OpenClaw Gateway를 이미 쓰고 있다면, 기억 계층은 플러그인 설정만 추가하면 되고 스택을 갈아엎을 필요가 없습니다.

3. 10분 실습: OpenClaw 플러그인 설치와 활성화

아래는 OpenClaw(≥ 2026.3.13)가 설치된 머신 기준입니다. Cloud Mac에서는 먼저 node -v가 22.16 이상인지 확인하세요.

3.1 플러그인 설치

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

업그레이드 시에는 네이티브 명령을 쓰세요. 시맨틱 버전 범위 때문에 플러그인이 비활성화되는 일을 피할 수 있습니다.

openclaw plugins update @tencentdb-agent-memory/memory-tencentdb

3.2 제로 설정으로 장기 기억 켜기

~/.openclaw/openclaw.json을 편집합니다.

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

저장 후 Gateway를 재시작합니다. 플러그인이 대화 기록, 기억 추출, 시나리오 요약, Persona 생성, 다음 턴 recall을 자동 처리합니다. 데이터는 기본적으로 로컬 SQLite에 저장되며 Tencent Cloud 계정은 필요 없습니다.

3.3 선택: 단기 기억 압축 활성화(≥ 0.3.4)

장시간 작업이나 다단계 도구 체인에서는 켜는 것을 권장합니다. 두 단계로 진행합니다.

1단계 — contextEngine 슬롯 등록:

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

2단계 — 저장소 루트에서 공식 patch 실행(after-tool-call 훅 주입):

bash scripts/openclaw-after-tool-call-messages.patch.sh

스크립트는 TencentDB-Agent-Memory/scripts에 있습니다. 저장소를 clone한 뒤 실행하세요.

3.4 검수 체크리스트(5분)

1. 같은 세션에서 출력이 큰 도구를 3회 연속 실행하고, 컨텍스트에 전문 로그 대신 Mermaid 그래프가 나타나는지 확인합니다.
2. 새 세션을 열어 「지난번 말한 코드 스타일이 뭐였지?」라고 물어 L1/L3 정보가 recall되는지 봅니다.
3. 로컬 데이터 디렉터리(기본 SQLite 파일) 크기가 대화와 함께 늘어나는지 확인합니다. PoC 단계에서는 정기 백업을 권장합니다.

다른 Agent 스택도 비교 중이라면, Kvmjet의 Strix AI Agent 배포 가이드로 「기억 계층 없음」과 「있음」의 장시간 작업 차이를 보는 것도 도움이 됩니다. Security Agent와 Coding Agent가 원하는 기억 품질은 다르지만 Token 경제학은 비슷합니다.

4. Cloud Mac / Apple Silicon 연동 시나리오

메모리 엔진은 상시 백그라운드 서비스라 「가끔 IDE를 켜는」 워크로드와 리소스 프로필이 다릅니다. Kvmjet M4 Cloud Mac에서 자주 맞는 시나리오는 다음과 같습니다.

• OpenClaw Gateway 24×7: M4 Mac mini 대기 전력 약 4W. 내부 당직 Agent에 적합합니다. 기억용 SQLite를 Gateway와 같은 머신에 두면 네트워크 지연과 데이터 반출 우려를 줄일 수 있습니다.
• 통합 메모리 + sqlite-vec: Apple Silicon의 높은 메모리 대역폭이 벡터 검색에 유리합니다. 16GB 노드에서 Gateway, 기억 DB, 경량 Ollama 평가를 함께 돌릴 수 있어 별도 x86 벡터 DB 서버가 필요 없습니다.
• iOS / Flutter 팀 동일 도메인: Xcode 빌드, Fastlane, Coding Agent를 같은 Cloud Mac에서 돌릴 때 Agent Memory는 「이 앱의 인증서 Profile 별칭」「Flutter flavor 이름」을 기억합니다. 원격 M4 빌드 머신 CI/CD 방안과 병행하면 「빌드 머신은 여기, Agent는 다른 클라우드」식 맥락 단절을 줄일 수 있습니다.
• 로컬 우선 컴플라이언스: 기본 SQLite 백엔드는 클라우드 강제가 아닙니다. 금융·의료 PoC는 Cloud Mac 내부망에서 검증한 뒤 필요 시 TCVDB로 전환하는 편이, 대화 로그를 제3자 SaaS로 보내는 것보다 보안 심사를 통과하기 쉽습니다.

5. 비용·성능·리스크 비교

「자체 기억」과 「맨 OpenClaw / 순수 RAG」를 한 표에서 봅니다(2026년 3분기 대략치, 20인 팀·월 Agent Token 500만 가정).

API 요금과의 관계: 기억 계층이 아낀 Token은 OpenAI / Anthropic 청구서에 바로 반영됩니다. 차세대 모델 예산을 짜고 있다면 Kvmjet GPT-6 API 요금 전망도 함께 보세요. 다단계 Agent 호출에서는 기억 압축이 다음 세대 가격 인하를 기다리는 것보다 효과적인 경우가 많습니다.

체감 성능: 로컬 sqlite-vec recall 지연은 보통 밀리초~백 밀리초 수준이고, 병목은 「L1/L3에 기억을 쓰는 LLM 호출」 쪽에 가깝습니다. 긴 세션에서는 offload를 켜지 않으면 L0 쓰기 빈도가 턴 간격을 늘립니다.

리스크 체크: (1) SQLite 손상 대비 백업 (2) Persona 오기록은 영구 오염 — 프로덕션에서는 L3 갱신 샘플 검수 (3) patch 스크립트는 OpenClaw 업그레이드 시 재실행 — 운영 runbook에 명시.

6. 자주 묻는 질문(FAQ)

TencentDB Agent Memory는 인터넷이나 Tencent Cloud 계정이 필요한가요?

기본 설정에서는 필요 없습니다. 로컬 SQLite + sqlite-vec으로 대화와 기억이 머신 안에 남습니다. 엔터프라이즈 멀티 노드나 대규모 벡터 검색에는 TCVDB로 전환할 수 있지만, 10분 PoC는 완전 오프라인으로 충분합니다.

단기 기억 압축과 장기 기억의 차이는?

단기는 현재 세션 안의 긴 작업용 — 로그를 내리고 Mermaid 그래프만 남깁니다. 장기는 세션을 넘음 — 대화에서 Atom, Scenario, Persona를 정제합니다. 장기만 켜도 「사용자를 기억」할 수 있지만, 다도구·다단계 코딩 Agent에는 둘 다 켜는 것을 권장합니다.

Cloud Mac에서 돌리면 어떤 이점이 있나요?

저전력 상시 운영, 로컬 벡터 검색에 유리한 통합 메모리, Xcode/Flutter 툴체인과의 동일 도메인 배치. 기억 데이터와 빌드 로그를 같은 머신에서 추적할 수 있어 「Agent는 클라우드, 코드는 로컬」보다 VPN·권한 단절이 적습니다.

OpenClaw 전용인가요?

아닙니다. Hermes Gateway용 공식 Docker·마운트 절차가 있고, 자체 프레임워크도 저장소 SDK로 연동할 수 있습니다. OpenClaw 경로가 가장 짧으며, Kvmjet OpenClaw 시리즈를 이미 쓰는 독자에게 맞습니다.

7. 정리와 다음 단계

TencentDB Agent Memory는 「Agent 장기 기억」을 10분 만에 켤 수 있는 OpenClaw 플러그인으로 구체화했습니다. 로컬 SQLite 무의존, L0–L3 계층 추적, 단기 offload로 Token을 크게 줄입니다. iOS/Flutter/AI 개발자의 다음 액션은 다음과 같습니다.

• PoC용 Cloud Mac에서 본문 3절 절차를 마치고 검수 체크리스트를 통과하기;
• Token을 가장 많이 쓰는 실제 워크플로(예: 대규모 리포지토리 리팩터 Agent)로 1주 A/B;
• SQLite + refs 백업 정책을 확정한 뒤 TCVDB나 프로덕션 노드 통합 검토.

기억 계층이 들어가야 Agent가 매번 「당신은 누구? 프레임워크는 뭐?」라고 묻는 신입이 아니라, 프로젝트를 아는 파트너에 가까워집니다.