Hindsight — OpenClaw 장기기억 플러그인

[!note] 수정이력 | 2026-05-07 20:58, 미미 (openclaw)

OpenClaw 에이전트에 생물모방형(biomimetic) 장기기억을 부여하는 플러그인. 대화를 자동 저장하고, 관련 기억을 매 턴마다 자동 주입하여 에이전트가 과거 문맥을 기억하게 만든다.

📌 핵심 개념

기능	설명
Auto-Recall	매 턴 시작 전 관련 기억을 자동 주입 (최대 1024토큰)
Auto-Retain	매 턴 종료 후 대화를 자동 저장, 팩트/엔티티/관계 추출
피드백 루프 방지	주입된 `<hindsight_memories>` 태그를 저장 전 자동 제거 → 중복 기억 방지
동적 뱅크	에이전트/채널/사용자별 격리된 메모리 뱅크 자동 생성

🛠️ 설치 및 설정

설치

# 1. 플러그인 설치
openclaw plugins install @vectorize-io/hindsight-openclaw

# 2. 인터랙티브 설정 마법사
npx --package @vectorize-io/hindsight-openclaw hindsight-openclaw-setup

# 3. 게이트웨이 시작
openclaw gateway

3가지 모드

모드	설명	적합한 경우
Cloud	Vectorize 관리형 Hindsight. API 토큰만 입력	빠른 시작, 관리 부담 최소
External API	자체 Hindsight 서버 연결	다중 인스턴스, 프로덕션
Embedded Daemon	로컬에 hindsight-embed 데몬 실행	단일 인스턴스, 로컬 우선

비인터랙티브 설정 (CI/스크립트용)

# Cloud + SecretRef
npx --package @vectorize-io/hindsight-openclaw hindsight-openclaw-setup \
  --mode cloud --token-env HINDSIGHT_CLOUD_TOKEN

# External API (인증 없음)
npx --package @vectorize-io/hindsight-openclaw hindsight-openclaw-setup \
  --mode api --api-url https://mcp.hindsight.example.com --no-token

# Embedded + OpenAI + SecretRef
npx --package @vectorize-io/hindsight-openclaw hindsight-openclaw-setup \
  --mode embedded --provider openai --api-key-env OPENAI_API_KEY

# Embedded + Claude Code (API 키 불필요)
npx --package @vectorize-io/hindsight-openclaw hindsight-openclaw-setup \
  --mode embedded --provider claude-code

⚙️ 설정 옵션 전체

~/.openclaw/openclaw.json → plugins.entries.hindsight-openclaw.config 경로

기본 설정

옵션	기본값	설명
`apiPort`	`9077`	로컬 데몬 포트
`daemonIdleTimeout`	`0`	데몬 유휴 종료 시간(초), 0=永不
`embedVersion`	`"latest"`	hindsight-embed 버전
`llmProvider`	—	메모리 추출용 LLM (openai, anthropic, gemini, groq, ollama, claude-code, openai-codex)
`llmModel`	프로바이더 기본값	LLM 모델
`llmApiKey`	—	API 키 (SecretRef 권장)
`llmBaseUrl`	—	OpenAI 호환 프로바이더 URL (예: OpenRouter)

뱅크/격리 설정

옵션	기본값	설명
`dynamicBankId`	`true`	문맥별 동적 뱅크 생성
`bankId`	—	`dynamicBankId: false`일 때 고정 뱅크 ID
`bankIdPrefix`	—	뱅크 ID 접두어 (예: “prod”)
`dynamicBankGranularity`	`["agent","channel","user"]`	뱅크 ID 파생 필드
`bankMission`	—	뱅크의 정체성/목적. reflect에만 영향
`retainMission`	—	retain 시 추출 방향 지정
`observationsMission`	—	observation 합성 방향 지정

Recall(회상) 설정

옵션	기본값	설명
`autoRecall`	`true`	매 턴 자동 기억 주입
`recallBudget`	`"mid"`	회상 노력 (low/mid/high)
`recallMaxTokens`	`1024`	최대 주입 토큰 수
`recallTopK`	—	턴당 최대 기억 수 (무제한 기본)
`recallTypes`	`["world","experience"]`	회상할 메모리 유형
`recallContextTurns`	`1`	회상 쿼리에 포함할 이전 턴 수
`recallMaxQueryChars`	`800`	회상 쿼리 최대 길이
`recallPromptPreamble`	빌트인	기억 주입 전 프리앰블 텍스트
`recallInjectionPosition`	`"prepend"`	주입 위치: prepend/append/user
`recallRoles`	`["user","assistant"]`	회상 쿼리 구성 시 포함할 역할

Retain(저장) 설정

옵션	기본값	설명
`autoRetain`	`true`	매 턴 자동 저장
`retainRoles`	`["user","assistant"]`	저장할 메시지 역할
`retainFormat`	`"json"`	직렬화 형식 (json/text)
`retainToolCalls`	`true`	JSON 형식 시 도구 호출 포함 여부
`retainEveryNTurns`	`1`	N턴마다 저장 (1=매턴)
`retainOverlapTurns`	`0`	청크 저장 시 이전 턴 중복 포함
`retainTags`	`[]`	저장 시 태그 (예: `["source_system:openclaw"]`)
`retainSource`	`"openclaw"`	저장 메타데이터 source 값
`retainDocumentScope`	`"session"`	문서 범위 (session/turn)

세션 필터링

옵션	기본값	설명
`excludeProviders`	`["heartbeat"]`	제외할 프로바이더
`ignoreSessionPatterns`	`[]`	완전 제외 세션 패턴 (recall+retain 스킵)
`statelessSessionPatterns`	`[]`	읽기전용 세션 패턴 (retain 스킵)
`skipStatelessSessions`	`true`	stateless 세션의 recall도 스킵

글롭 패턴 예시:

agent:*:cron:** → 모든 cron 세션
agent:*:subagent:** → 모든 서브에이전트 세션

🔧 관리/운영 명령어

데몬 상태 확인

# 데몬 실행 상태
uvx hindsight-embed@latest -p openclaw daemon status

# 데몬 로그 확인
tail -f ~/.hindsight/profiles/openclaw.log

# 설정 확인
cat ~/.hindsight/profiles/openclaw.env

기억 검색

# 메모리 검색
uvx hindsight-embed@latest -p openclaw memory recall openclaw "검색어"

과거 대화 백필 (Backfill)

# 드라이런
npx --package @vectorize-io/hindsight-openclaw hindsight-openclaw-backfill \
  --openclaw-root ~/.openclaw --dry-run

# 실제 실행
npx --package @vectorize-io/hindsight-openclaw hindsight-openclaw-backfill \
  --openclaw-root ~/.openclaw --resume

# 특정 에이전트만
npx --package @vectorize-io/hindsight-openclaw hindsight-openclaw-backfill \
  --openclaw-root ~/.openclaw --agent main

# 뱅크 전략 지정
node dist/backfill.js \
  --openclaw-root ~/.openclaw \
  --bank-strategy agent \
  --agent proj-run \
  --resume

OpenClaw 설정 변경

# LLM 프로바이더 변경
openclaw config set plugins.entries.hindsight-openclaw.config.llmProvider openai

# API 키 (SecretRef로 환경변수 참조)
openclaw config set plugins.entries.hindsight-openclaw.config.llmApiKey \
  --ref-source env --ref-provider default --ref-id OPENAI_API_KEY

# External API 모드
openclaw config set plugins.entries.hindsight-openclaw.config.hindsightApiUrl https://mcp.hindsight.example.com
openclaw config set plugins.entries.hindsight-openclaw.config.hindsightApiToken \
  --ref-source env --ref-id HINDSIGHT_API_TOKEN

💡 실전 활용 팁

1. 크로스 채널 사용자 기억 공유

기본 설정은 ["agent","channel","user"] → 같은 사용자도 채널이 다르면 기억이 분리됨.

같은 플랫폼 내에서 기억 공유:

{ "dynamicBankGranularity": ["provider", "user"] }

모든 플랫폼에서 기억 공유:

{ "dynamicBankGranularity": ["user"] }

2. retainMission으로 기억 품질 향상

{
  "retainMission": "사용자 선호, 진행 중인 프로젝트, 반복 약속, 중요한 맥락 등 지속적으로 유용한 사실을 추출하라. 일회성 잡담과 임시 작업은 제외하라."
}

3. 서브에이전트/크론 세션 메모리 관리

{
  "ignoreSessionPatterns": ["agent:*:cron:**"],
  "statelessSessionPatterns": ["agent:*:subagent:**"],
  "skipStatelessSessions": false
}

→ 크론은 완전 제외, 서브에이전트는 읽기만 가능

4. 프롬프트 캐싱 최적화

큰 정적 시스템 프롬프트가 있으면 recallInjectionPosition: "append"로 설정하여 프롬프트 캐싱 유지.

5. 청크 저장으로 비용 절감

{
  "retainEveryNTurns": 3,
  "retainOverlapTurns": 1
}

→ 3턴마다 저장, 이전 1턴 중복 포함

6. 디버그 성능 타이밍

{ "debugPerfTiming": true }

→ recall/retain 소요 시간을 info 로그로 출력

🔍 현재 미미 설정 (2026-05-07 기준)

모드: External API
뱅크: mimi
autoRecall: true
autoRetain: true
포트: 9177 (Control Plane → rem-h.pinksky.kr)

Hindsight — OpenClaw 장기기억 플러그인

Hindsight — OpenClaw 장기기억 플러그인

📌 핵심 개념

🛠️ 설치 및 설정

설치

3가지 모드

비인터랙티브 설정 (CI/스크립트용)

⚙️ 설정 옵션 전체

기본 설정

뱅크/격리 설정

Recall(회상) 설정

Retain(저장) 설정

세션 필터링

🔧 관리/운영 명령어

데몬 상태 확인

기억 검색

과거 대화 백필 (Backfill)

OpenClaw 설정 변경

💡 실전 활용 팁

1. 크로스 채널 사용자 기억 공유

2. retainMission으로 기억 품질 향상

3. 서브에이전트/크론 세션 메모리 관리

4. 프롬프트 캐싱 최적화

5. 청크 저장으로 비용 절감

6. 디버그 성능 타이밍

🔍 현재 미미 설정 (2026-05-07 기준)

🔗 참고 링크