결론 (미리보기)

일본어 환경에서 Hindsight를 쾌적하게 사용하려면, 기본 설정에서 4가지 레이어를 변경해야 합니다.

레이어	기본 설정의 문제점	대처 방법
Embedding	영어 전용 모델 (bge-small-en-v1.5)	BAAI/bge-m3 (multilingual)로 변경
Reranker	영어용 cross-encoder	hotchpotch/japanese-reranker-xsmall-v2로 변경
Lexical 검색	PostgreSQL의 english tsvector로 인해 일본어가 형태소 분석(분절)되지 않음	HINDSIGHT_API_TEXT_SEARCH_EXTENSION=vchord로 전환
사실(Fact) 추출 언어	프롬프트의 영어 편향(bias)으로 인해 기억이 영어화됨	HINDSIGHT_API_RETAIN_MISSION / HINDSIGHT_API_OBSERVATIONS_MISSION으로 일본어 지시를 명시

이에 더해, GPU가 없는 환경에서는 reranker의 지연 시간(latency) 대책(BUCKET_BATCHING / MAX_CANDIDATES 축소)과 LLM의 가치 판단 품질(OpenRouter을 통해 structured output을 지원하는 provider로 고정)이 운용 품질을 좌우합니다.

본 기사는 이러한 설정들을 정리한 실운용 기반의 가이드입니다. 자세한 내용은 각 섹션에서 설명합니다.

서론

Hindsight (by Vectorize)는 LLM 에이전트에게 장기 기억을 부여하기 위한 셀프 호스팅 가능한 메모리 백엔드(memory backend)입니다. PostgreSQL + pgvector를 기반으로, 대화 로그에서 자동으로 사실을 추출·요약하고, RAG 기반으로 검색할 수 있는 구조를 제공합니다.

공식 문서는 영어 사용자용으로 작성되어 있어, 일본어 환경에서 그대로 실행하면 여러 레이어에서 영어 전제 조건이 남게 되어 기억의 회상(recall) 품질이 떨어지거나, 저장되는 관찰(observation) 내용이 영어로 변해버립니다.

본 기사에서는 GPU 없는 Linux 로컬 환경에서 Hindsight v0.5.6을 일본어 환경으로 운용하기 위한 설정 포인트를 정리합니다. Hermes Agent나 Claude Code와 같은 에이전트를 메모리 백엔드에 연결하는 용도를 상정하고 있으나, 설정 방식은 다른 에이전트에도 통용됩니다 (2026년 5월 시점의 정보입니다).

우선 어떤 구성을 선택할 것인가

신규 설치인지 기존 DB를 사용하는지에 따라 해야 할 일이 크게 달라집니다. 자신의 케이스를 확인한 후 해당 섹션으로 이동해 주세요.

상황	권장 embedding	권장 reranker	BM25	참조 섹션
신규 + 기술 메모·일영 혼재 로그 (필자 채택)	BAAI/bge-m3 (1024 dim)	hotchpotch/japanese-reranker-xsmall-v2	vchord	템플릿 (본 기사)
기존 384 dim DB를 1024 dim으로 이행	BAAI/bge-m3	위와 동일	vchord로 이행 권장	Embedding migration 섹션

왜 기본 설정이 일본어에 취약한가

Hindsight를 일본어 환경에서 그대로 사용하면 4가지 레이어에서 문제가 발생합니다.

1. Embedding이 영어에 치우침

기본 모델은 BAAI/bge-small-en-v1.5 (384 dim, 영어 전용)입니다. 일본어 쿼리로 관련 메모리가 반환되지 않는다면 우선 이 부분을 의심해야 합니다.

2. Reranker가 영어용임

기본값인 cross-encoder/ms-marco-MiniLM-L-6-v2는 영어용 cross-encoder입니다. Embedding을 통해 관련 후보가 올라오더라도, reranker에서 일본어 텍스트의 점수가 적절하게 나오지 않을 가능성이 있습니다.

3. Lexical 검색 (BM25 leg)이 일본어를 형태소 분석(분절)하지 못함

Hindsight v0.5.6의 native text search 경로는 to_tsvector('english', ...)입니다.

상당한 처리를 수행하며, 일본어를 형태소 분석(分かち書き)하지 않습니다. API 응답에서 bm25_count=300이라고 표시되어 있더라도, 그것이 "유용한 일본어 lexical 후보를 찾아냈다"는 증거는 아닙니다.

실태를 확인하려면:

SELECT to_tsvector('english', 'Hermesのgatewayの再起動ループの対処法は60秒待ってロックを削除すること');
-- → 일본어는 1토큰의 덩어리로 취급되어, lexical 검색에 사용할 수 없음

4. 추출되는 기억이 영어화될 수 있음

Embedding/Reranker를 다국어 대응으로 설정하더라도, memory_units.text (retain이 추출한 사실)나 observation (consolidation이 생성한 관찰)이 영어로 저장되는 문제는 별개의 레이어입니다.

원인은 다음과 같습니다:

• Pydantic JSON Schema의 Field(description=...)가 영어임
• retain 프롬프트의 dominant-language 판정 로직
• consolidation 프롬프트 내에 고정된 영어 예문("Alice often works long hours past midnight." 등)이 매립되어 있어, 이것이 in-context bias가 되어 observation을 영어로 기울게 함
• Hermes와 같은 기술계 에이전트에서는 skill 문서, tool output, 코드 블록 등의 영어 텍스트가 많아 영어로 기울어지기 쉬움

이는 retain_mission / observations_mission 설정으로 대처합니다 (후술).

모델 선택 가이드

Embedding 모델

모델	dim	특징	적합한 용도
BAAI/bge-small-en-v1.5	384	기본값, 영어 전용	❌ 일본어에는 부적합
BAAI/bge-m3	1024	multilingual, 고품질	code-mixed corpus, 기술 메모
cl-nagoya/ruri-v3-70m	384	일본어 특화, prefix 전제	현시점에서는 미채택. PR #1585 merge 후의 미래 후보
sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2	384	다국어·경량 (미시험)	dim migration을 피하면서 다국어 대응

실운용에서 판명된 사항:

• BAAI/bge-m3 (1024 dim)는 일-영 혼재 기술 메모에서 가장 안정적인 recall을 보여주었습니다. 신규 DB를 처음부터 bge-m3로 초기화하는 경우, 384→1024의 schema migration은 발생하지 않습니다.
• cl-nagoya/ruri-v3-70m은 latency가 bge-m3의 약 절반(평균 2배 빠름) 수준이라 매력적이지만, model name·env var·명령어 등의 영어 technical token을 포함하는 operational 쿼리에서 keyword 유지가 약하다는 문제가 있습니다. 적어도 필자의 code-mixed operational corpus에서는 bge-m3보다 keyword anchor 유지가 약하여, 기술 메모 용도의 제1후보로 삼지 않았습니다. 일본어 순수 문장 중심의 corpus(의사록, 일본어 문서 등)에서는 유망하지만, 설정에 필요한 query/document prefix (검색 쿼리: / 검색 문서:)를 Hindsight에 전달하는 env가 upstream PR에 아직 머지되지 않았기 때문에, 현시점에서는 prefix 없는 운용이 되어 모델 사양대로의 성능이 나오지 않습니다. PR merge를 기다린 후 다시 평가할 예정입니다.
• sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2는 384 dim을 유지하면서 다국어 대응이 가능한 이론상의 후보이지만, 필자 환경에서는 미시험입니다. 실제 recall 품질은 corpus에 대해 별도의 벤치마크가 필요합니다.

Reranker 모델

모델	파라미터 수	CPU 속도 기준(필자 환경)	비고
cross-encoder/ms-marco-MiniLM-L-6-v2	—	—	기본값, 영어용
BAAI/bge-reranker-v2-m3	278M	~48s/300개 후보	고품질·multilingual, CPU에는 무거움
hotchpotch/japanese-reranker-xsmall-v2	36.8M	~7-13s/300개 후보	일본어 특화, 품질·속도의 밸런스가 좋음
hotchpotch/japanese-reranker-tiny-v2	—	더 빠름	xsmall 대비 약 -6.9pt (MIRACL -10pt)의 품질 비용 발생

권장: 일본어 메모리에 대해서는 hotchpotch/japanese-reranker-xsmall-v2가 현시점(2026년 5월)의 스위트 스팟(sweet spot)입니다. tiny-v2는 빠른 대신 품질 비용이 커서, operational anchor 쿼리(모델명, env var 명, 커맨드 등)에서의 keyword hit가 현저히 떨어집니다. 영어 비중이 높은 corpus에서는 bge-reranker-v2-m3를 시도해 볼 가치가 있습니다.

reranker 교체는 env(환경 변수) 수정만으로 완료되며, embedding/index에는 영향을 주지 않습니다.

LLM (retain / reflect / consolidation 용)

LLM의 품질은 "무엇을 기억으로 남길 것인가"라는 가치 판단에 직결됩니다.

경량 LLM (예: google/gemini-2.5-flash-lite)의 문제점:

• "흘러 들어온 텍스트를 어쨌든 요약하기만 하는" 경향이 있어, 장기적으로 가치 있는 지견과 일시적인 작업 메모를 구분하지 못함
• observation의 과잉 생성, world(지속적 사실)의 누락이 발생하기 쉬움 - mission으로 억제하려 해도 근본적인 해결책이 되지 않음

권장 구성 (2026년 5월 시점): openai/gpt-oss-120b (OpenRouter 경유, Groq provider 고정)

HINDSIGHT_API_LLM_PROVIDER=openrouter
HINDSIGHT_API_LLM_MODEL=openai/gpt-oss-120b
HINDSIGHT_API_LLM_EXTRA_BODY='{"provider":{"order":["groq"],"allow_fallbacks":false,"require_parameters":true},"reasoning":{"effort":"low"}}'

EXTRA_BODY의 각 필드 의미:

필드	의미	필요한 이유
provider.order=["groq"]	OpenRouter의 routing을 Groq로 고정	기본 routing은 DekaLLM·Google 등으로 연결되어 JSON schema strict가 깨짐 (structured output을 지원하지 않는 provider로 전달되기 때문)
allow_fallbacks=false	fallback 무효화	structured output을 지원하는 provider로만 한정
require_parameters=true	위와 동일한 보험	—
reasoning.effort=low	reasoning token을 30% 절감	gpt-oss-120b는 reasoning model이므로, 미지정 시 전체 token의 약 66%가 reasoning에 소모됨

권장 설정 템플릿

패턴 1: 품질 우선 (code-mixed corpus, 신규 DB 또는 side stack으로 migration 완료)

이 구성은 신규 설치, 또는 기존 DB를 side stack으로 1024 dim으로 이관 완료한 경우를 위한 것입니다.

일본어 + 영어 기술 용어가 혼재된 기술 메모·에이전트 대화 로그용.

LLM

HINDSIGHT_API_LLM_PROVIDER=openrouter
HINDSIGHT_API_LLM_API_KEY=${OPENROUTER_API_KEY}
...

함께 retain/observations mission도 설정합니다 (후술할 섹션 참조).

채택하지 않은 구성에 대하여

본 기사에서는 필자가 실제로 운영 환경에서 사용한 구성만을 템플릿으로 게재하고 있습니다.

Ruri v3 ( : 신규/빈 DB라면 384 dim으로 schema migration이 불필요하고, latency도 빨라 유망했으나, 필자의 code-mixed corpus에서는 bge-m3보다 keyword anchor 유지가 약해 채택을 보류했습니다. 또한 Ruri v3가 필요로 하는 query/document prefix (cl-nagoya/ruri-v3-70m의 検索クエリ: / 検索文書:)를 Hindsight에 전달하는 env가 upstream PR #1585 미머지 상태이므로, 현 시점에서는 prefix 없이 운용되어 모델 사양대로의 성능이 나오지 않습니다. PR merge 후 일본어 순수 문장 corpus에서의 재평가를 예정하고 있습니다. -
: 384 dim으로 다국어 대응이 가능한 이론상의 후보이지만, 필자의 환경에서는 미시험 상태입니다. sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2

Fact Extraction의 일본어화 (mission 설정)

embedding/reranker를 일본어 대응으로 설정하더라도, 저장되는 memory_units.text나 observation이 영어로 되는 문제는 mission 설정으로 해결합니다. 설정 템플릿과 함께 반드시 설정해 주세요.

retain_mission

# docker-compose.yml의 environment 하위에 기술
environment:
HINDSIGHT_API_RETAIN_MISSION: |
...

observations_mission (Alice example 문제)

consolidation 프롬프트 내에 고정된 영어 예문 ("Alice often works long hours past midnight." 등)이 삽입되어 있으며, 이것이 in-context bias가 되어 observation을 영어로 치우치게 만듭니다. mission을 통해 이 편향을 상쇄합니다:

# docker-compose.yml의 environment 하위에 기술
environment:
HINDSIGHT_API_OBSERVATIONS_MISSION: |
...

설정 방법

모든 bank 공통: compose의 environment에 설정 (권장)

신규 bank도 자동으로 따라오기 때문에, 전체 설정으로서 관리가 가장 쉽습니다. 위의 yaml 형식 그대로 docker-compose.yml에 작성할 수 있습니다.

bank별로 개별 설정하고 싶은 경우: 대시보드에서 변경

http://localhost:9999의 Control Plane UI에서 bank를 선택하여 mission 필드를 직접 편집할 수 있습니다. GUI 조작이므로 명령어가 필요 없어 직관적이지만, env 설정을 bank 레벨에서 덮어쓴다는 점에 주의하십시오. 의도치 않게 이 덮어쓰기가 남게 되면, env를 변경해도 반영되지 않게 됩니다.

BM25 백엔드를 vchord로 전환하기

왜 native text search로는 불충분한가

Hindsight의 native text search path (to_tsvector('english', ...))는 일본어를 형태소 분석(분할)하지 않습니다. bm25_count 건수가 반환되더라도, 그것은 lexical 검색에서 일본어 쿼리에 일치하는 후보가 아닙니다.

-- 일본어 쿼리로 기대하는 행에 정말로 일치하는지 확인
SELECT mu.id, mu.text
FROM memory_units mu
...

vchord로의 전환

HINDSIGHT_API_TEXT_SEARCH_EXTENSION=vchord

로 설정하면, VectorChord-BM25와 tokenize(query, 'llmlingua2')를 사용하는 backend (백엔드)로 전환됩니다. 일본어 / 다국어 lexical recall (어휘 검색 재현율)의 최우선 후보입니다.

필요한 DB image (이미지): tensorchord/vchord-suite

(pg_tokenizer / vchord_bm25 extension (확장) 포함)

# docker-compose.yml의 postgres 부분
services:
hindsight-postgres:
...

신규 DB에 vchord 도입

이 절은 신규 설치를 위한 것입니다. 기존 DB가 있는 경우 「기존 DB의 마이그레이션」을 참조하십시오.

신규 DB의 경우, vchord 대응 image (이미지)와 HINDSIGHT_API_TEXT_SEARCH_EXTENSION=vchord를 처음부터 지정하여 기동합니다. 기존 데이터가 없으므로 native (네이티브) → vchord 변환은 불필요합니다. Hindsight가 기동 시 필요한 extension (확장)과 schema (스키마)를 초기화합니다.

기동 후 확인:

-- vchord 관련 extension (확장)이 활성화되었는지 확인
SELECT extname FROM pg_extension
WHERE extname IN ('vchord_bm25', 'pg_tokenizer');

기존 DB의 마이그레이션 (사이드 스택 방식)

권장하는 마이그레이션 절차:

• 운영 환경은 건드리지 말 것 — 운영 중인 Hindsight/Postgres는 기동 상태를 유지합니다.
• side stack (사이드 스택) 구축 — 별도의 port (포트, 예: API 8898 / UI 9989)로 docker-compose.vchord.yml을 준비합니다.
• 운영 환경의 dump (덤프)를 restore (복구) — pg_dump -Fc로 취득한 백업을 새로운 volume (볼륨)에 restore (복구)합니다.
• tokenizer (토크나이저) bootstrap (부트스트랩) 및 lexical index (어휘 인덱스) 변환 — vchord용 image (이미지)로 기동한 후, tokenize(text, 'llmlingua2')를 사용하여 기존 rows (행)의 lexical index (어휘 인덱스)용 데이터를 vchord 형식 (bm25vector)으로 변환합니다.
• 동일 query set (쿼리 세트)으로 벤치마크 (성능 측정) — 운영 환경(native) vs 사이드 스택(vchord)을 비교합니다.
• GO 판정 후 blue/green 전환 — 기존 volume (볼륨)은 백업으로서 retention (보존) 기간 동안 유지합니다.

벤치마크 (성능 측정) 지표: bm25_count의 건수가 아니라, 기대하는 관련 ID의 Recall@50 / top-50 Jaccard / keyword hit ratio (키워드 적중률)로 판단합니다.

Embedding Migration (임베딩 마이그레이션) 주의사항

이 절은 기존 DB에서 embedding (임베딩)의 dimension (차원)이 변경되는 전환(384→1024 등)을 수행하는 경우에만 필요합니다. 신규 설치 시에는 건너뛰어도 됩니다.

기동 거부 에러

memory_units에 데이터가 남아 있는 상태에서 dimension (차원)을 변경하면:

RuntimeError: Cannot change embedding dimension from 384 to 1024

메시지와 함께 기동이 거부됩니다.

migration (마이그레이션) 절차 개요

• 백업을 취함 (pg_dump -Fc, 모델 명과 dim (차원)을 파일명에 포함)
• memory_units / mental_models 테이블을 truncate (절단) 또는 DELETE (삭제)
• ALTER COLUMN embedding TYPE vector(1024)로 vector (벡터) 열의 타입을 변경
• per-bank HNSW index (뱅크별 HNSW 인덱스)를 DROP (삭제) → ALTER (변경) → re-CREATE (재생성)
• 새 모델을 지정하여 Hindsight를 기동
• /reprocess로 모든 chunk (청크)를 재 retain (유지/보관)

자주 발생하는 함정

• chunks (청크)가 남아 있으면 /reprocess가 델타 스킵(delta skip)을 수행함. memory_units만 삭제하고 /reprocess를 실행할 것.

하지만 chunks가 남아 있으면 차분이 없다고 판단하여 재생성되지 않습니다 -
：hindsight-admin backup / restore는 embedding dimension 변경의 rollback(롤백)에는 사용할 수 없습니다.

backup / restore는 동일한 schema(스키마)로의 복원에는 유용하지만, embedding dimension을 변경한 DB에 대한 차분 rollback이나 re-embedding(재임베딩) 수단은 아닙니다. authoritative(권위 있는)한 rollback 백업은 pg_dump -Fc로 수행합니다.

HNSW DDL은 dim-agnostic(차원 독립적)입니다：pg_get_indexdef()가 반환하는 DDL에는 vector(N)의 N이 포함되지 않습니다. 동일한 DDL 파일을 384 또는 1024로 ALTER(변경)한 후에도 모두 재사용할 수 있습니다.

：pg_restore --list에는 seekable input(탐색 가능한 입력)이 필요합니다. gunzip -c dump.gz | pg_restore --list -는 실패합니다 (pg custom format은 TOC를 끝에 가지기 때문입니다). 일단 압축을 해제한 후 pg_restore --list를 실행합니다.

GPU 없는 운용 시의 CPU 부하 대책 (autorecall 가속화)

CPU 환경에서는 autorecall 시간의 대부분이 reranker(리랭커)에 의해 지배됩니다. GPU 없이 취할 수 있는 최적화 방법은 3가지입니다.

1. BUCKET_BATCHING (품질 저하 없음)

HINDSIGHT_API_RERANKER_LOCAL_BUCKET_BATCHING=true

텍스트를 길이에 따라 정렬하여 padding(패딩)의 낭비를 줄이는 최적화로, 공식 blog에서는 36~54%의 가속화가 보고되었습니다. ranking(랭킹) 품질은 변하지 않으므로 최우선으로 활성화합니다.

2. MAX_CANDIDATES 제한

HINDSIGHT_API_RERANKER_MAX_CANDIDATES=100 # 기본값 300

reranker의 비용은 후보 수에 거의 선형적으로 비례합니다. 300에서 100으로 줄이면 약 1/3로 절감할 수 있습니다. 품질 저하가 보이면 150 / 200으로 다시 올립니다.

3. MAX_CONCURRENT 억제

HINDSIGHT_API_RERANKER_LOCAL_MAX_CONCURRENT=2 # 기본값 4

기본값 4에 PyTorch가 자동으로 감지한 스레드 수를 곱한 합계가 물리 코어 수를 초과하면 thrash(스래싱)의 원인이 됩니다. 동시 recall이 여러 개 발생하는 환경에서는 2로 낮춤으로써 경합을 억제할 수 있습니다. 동시 recall이 없는 단발 실행에서는 기본적으로 latency(지연 시간)에 미치는 영향이 작습니다.

실측치 기준 (필자 환경, 약 300개 후보 기준)

• reranker 교체 (tiny-v2 → xsmall-v2): wall mean +11% (11.4s → 12.6s), p95는 오히려 단축 (17.9s → 14.4s)
• bge-reranker-v2-m3 (278M)는 300개 후보 시 ~48s로 너무 느려 상시 autorecall에는 부적합

LLM Migration의 함정

이 절은 LLM을 교체하는 경우에만 필요합니다. 신규 설치 시 처음부터 권장 LLM을 사용하는 경우에는 건너뛰어도 됩니다.

OpenRouter의 routing이 JSON schema strict를 깨뜨림

openai/gpt-oss-120b와 같은 인기 모델은 OpenRouter가 내부적으로 여러 provider(제공자)에게 routing(라우팅)합니다. JSON schema strict (structured output)를 지원하지 않는 provider (DekaLLM, Novita, Phala 등)로 routing될 경우, Hindsight가 요구하는 Pydantic 스키마가 깨진 fact(사실)가 반환됩니다.

반드시 provider.order로 provider를 고정하십시오. leaderboard(리더보드)의 값을 재현하려면, 해당 벤치마크를 실시한 provider (gpt-oss-120b의 경우 Groq)로 고정합니다.

reasoning token 절약

gpt-oss-120b

등 reasoning 모델은 effort을 지정하지 않으면 completion token의 60~70%가 reasoning에 소비됩니다. Hindsight는 reasoning trace를 저장하지 않기 때문에, "reasoning":{"effort":"low"}로 제한하면 거의 품질 저하 없이 30% 절감할 수 있습니다 (작성자 실측).

per-bank의 mission 설정이 env를 덮어쓰기

이전에 per-bank PATCH API에서 retain_mission을 설정한 bank가 있는 경우, env의 설정이 무효화됩니다. 마이그레이션 전에 반드시 확인하세요:

SELECT bank_id, jsonb_pretty(config) FROM banks
WHERE config ? 'retain_mission' OR config ? 'observations_mission';

0행이 조건입니다. 남아 있다면:

UPDATE banks SET config = config - 'retain_mission' WHERE ...;

reflect_mission (bank 고유의 identity 설정)은 남겨두어도 되지만, 언어 설정은 env를 single source of truth로 합니다.

container recreate 후 stuck operation