TencentDB Agent Memory 딥다이브
— "더 많이 기억"이 아니라 "더 잘 추론"하는 4계층 로컬 메모리 엔진

1프로젝트 한줄 요약

이 레포가 무엇을 하는 물건인가.

TencentDB Agent Memory는 두 개의 기둥으로 이루어진다. 하나는 위에서 말한 메모리 계층화(memory layering) 즉 장기 개인화 기억이고, 다른 하나는 기호 메모리(symbolic memory) 즉 작업 중 폭증하는 도구 로그를 외부 파일로 덜어내고(offload) 컨텍스트엔 Mermaid 다이어그램 한 장만 남기는 단기 기억 압축이다. 둘 다 "평평하게 쌓기"를 거부하고 계층으로 다룬다는 점에서 한 철학을 공유한다.

2왜 주목받는가

트렌딩 이유 · 평평한 벡터 메모리 대비 장점.

2025~2026년 에이전트 메모리(mem0, Letta/MemGPT, Zep 등)는 뜨거운 주제였지만, 대부분 "대화를 조각내 벡터 DB에 던지고 유사도로 꺼내는" 평평한 구조였다. 그 결과 회상은 맥락 없이 흩어진 조각들 사이의 깜깜이 검색으로 전락하기 쉽다. TencentDB Agent Memory가 주목받는 이유는 이 한계를 정면으로 공격하면서, 실측 벤치마크로 효과를 증명했기 때문이다.

저자들은 이 수치가 단발 턴이 아니라 긴 호흡의 연속 세션에서 측정됐다고 강조한다(예: SWE-bench는 세션당 50개 작업을 연속 수행해 실제 컨텍스트 누적 압력을 흉내). 즉 "오래 쓸수록 진가가 나는" 메모리다.

3기술 스택 전체 지도

런타임(백엔드)·저장/검색·LLM·인프라 각각.

① 런타임 & 언어 (백엔드)

전체가 TypeScript로 작성된 Node.js 플러그인이다(type: "module" ESM, Node ≥ 22.16). 빌드는 tsdown, 테스트는 vitest. OpenClaw 게이트웨이의 플러그인 SDK(pluginApi ≥ 2026.3.13)에 맞춰 index.ts가 훅·도구를 등록한다.

② 저장 & 검색 — 백엔드 추상화

핵심은 src/core/store/types.ts의 백엔드 무관 인터페이스(IMemoryStore)다. 상위 모듈(훅·도구·파이프라인)은 인터페이스만 의존하고, 구현체는 팩토리(factory.ts)가 설정에 따라 골라 끼운다.

③ 인프라 · 배포 · 통합

4아키텍처 심화 분석

대화 캡처 → 4계층 증류 → 자동 회상, 그리고 기호 메모리 오프로딩.

두 개의 엔진 — 장기 계층화 + 단기 기호화

이 플러그인은 사실상 두 시스템이 한 패키지에 들어있다. ① 장기 메모리(src/core/)는 세션을 넘는 개인화 기억(L0→L3)을, ② 단기 오프로딩(src/offload/)은 한 작업 안에서 폭증하는 도구 로그를 Mermaid로 압축한다. 둘은 같은 훅 지점(게이트웨이)에 등록되지만 목적이 다르다.

장기 메모리 — 회상이 일어나는 순간

사용자가 새 메시지를 보내면 before-agent-start 단계에서 auto-recall이 발동한다. L1 기억을 검색해 프롬프트 앞에 붙이고(per-turn 동적), L3 페르소나·L2 장면 내비게이션을 시스템 프롬프트 끝에 붙인다(캐시 가능). 에이전트가 답하고 나면 after-tool-call/턴 종료 시 auto-capture가 대화를 L0에 기록하고, 파이프라인 매니저에게 "이제 L1/L2/L3를 돌릴 때인가?"를 묻는다.

4계층 의미 피라미드 — 핵심

장기 메모리의 심장은 아래로 갈수록 증거(원문)에 가깝고, 위로 갈수록 구조(추상)에 가까운 피라미드다.

// 상위 모듈은 이 인터페이스에만 의존 (SQLite/TCVDB 구현 몰라도 됨)
interface IMemoryStore {
  // 능력 기반(capability): 벡터·FTS·하이브리드 지원 여부를 플래그로 노출
  // 결함 허용(fault-tolerant): 실패 시 throw 대신 빈 결과/false 반환
  searchL1Vector(...): Promise<L1SearchResult[]>;
  searchL1Fts(...):    Promise<L1FtsResult[]>;
  ...
}
// factory.ts 가 config.storeBackend 로 구현체 선택
switch (config.storeBackend) {
  case "tcvdb":  return new TcvdbMemoryStore(...);   // 텐센트 클라우드 벡터DB
  case "sqlite":
  default:       return new VectorStore(dbPath, dims, logger); // 로컬 기본
}

기호 메모리 — Mermaid로 로그를 압축

긴 작업에서 토큰을 가장 많이 먹는 건 장황한 중간 로그(검색 결과·코드·에러 트레이스)다. src/offload/는 이를 외부 파일(refs/*.md)로 덜어내고, 컨텍스트엔 node_id가 박힌 Mermaid 그래프 한 장만 남긴다. 에이전트는 이 기호 그래프 위에서 추론하다가, 세부 확인이 필요하면 node_id로 grep해 원문을 즉시 복구한다.

L2 Mermaid 파이프라인은 L1에서 직접 호출되지 않고 독립 트리거로 돈다 — ① 오프로드 jsonl에 node_id=null 항목이 임계치 이상 쌓이거나, ② 마지막 L2 실행 후 일정 시간이 지나면 발동한다(l2-mermaid.ts).

5디렉토리 구조 해부

src/core/(장기 메모리)와 src/offload/(기호 메모리)가 양대 축.

6학습 포인트 (기술별)

에이전트 메모리 시스템 설계에서 무엇을 배우나.

A. 계층형 메모리 — "평평하게 쌓지 말라"

가장 큰 교훈은 메모리는 형성도 회상도 계층적이어야 한다는 것이다. 모든 걸 한 벡터 DB에 던지면 회상이 깜깜이 검색이 된다. L0→L1→L2→L3처럼 추상도를 올리되, 각 층이 아래 층으로 내려가는 추적 경로를 유지하면 "요약의 편의 + 원문의 정확성"을 동시에 얻는다. RAG·노트 앱·로그 시스템 어디에도 옮길 수 있는 원칙이다.

B. 백엔드 추상화 + 결함 허용 강등

IMemoryStore 인터페이스는 "상위 모듈은 인터페이스에만 의존"의 교과서다. 덕분에 로컬 SQLite ↔ 텐센트 클라우드 벡터DB를 코드 변경 없이 갈아끼운다. 게다가 임베딩 키가 없으면 throw 하지 않고 키워드 검색으로 자동 강등한다 — "기능이 없으면 죽는다"가 아니라 "할 수 있는 만큼 한다"는 견고함.

C. 하이브리드 검색(RRF) — 키워드 + 벡터

순수 벡터 검색은 정확한 키워드(고유명사·코드)에 약하고, 순수 키워드는 의미 유사에 약하다. 이 레포는 FTS5 BM25 + 벡터 유사도를 RRF로 병합해 둘의 장점을 취한다. tools/memory-search.ts의 strategy(hybrid/embedding/fts) 자동 강등 로직이 좋은 참고서다.

D. 컨텍스트 엔지니어링 — 토큰을 기호로 압축

오프로딩 모듈은 "컨텍스트는 유한 자원"이라는 관점의 모범이다. 장황한 로그를 외부로 덜고 Mermaid 한 장 + node_id 인덱스만 남기면, 토큰을 60% 아끼면서도 grep으로 원문에 즉시 닿는다. 긴 호흡 에이전트(코딩·리서치)에서 컨텍스트 관리가 곧 성능임을 보여준다.

7시스템 / 환경 요구사항

"로컬 우선" 설계 — 기본은 외부 서비스 없이도 돈다.

8직접 해볼 수 있는 실습 과제

난이도별 5단계 — 설치 체험부터 미니 메모리 엔진 구현까지.

9관련 기술 심화 학습 로드맵

6주 코스 — 임베딩 검색 기초부터 계층형 에이전트 메모리 설계까지.

10핵심 키워드 사전

본문·소스에 나온 용어 빠른 참조.

11참고 링크

• GitHub: TencentCloud/TencentDB-Agent-Memory
• npm: @tencentdb-agent-memory/memory-tencentdb
• 호스트: OpenClaw · Hermes Gateway
• 관련 메모리 프로젝트: mem0 · Letta(MemGPT)
• 핵심 기술: sqlite-vec · SQLite FTS5 · Vercel AI SDK
• 로컬 LLM: node-llama-cpp · 다이어그램: Mermaid