Honcho 메모리
Honcho는 Hermes의 내장 메모리 시스템 위에 dialectic reasoning과 깊은 사용자 모델링을 더하는 AI-native 메모리 backend입니다. 단순한 key-value storage가 아니라, 대화가 끝난 뒤 그 대화를 reasoning하여 사용자의 선호, 커뮤니케이션 스타일, 목표, 반복 패턴을 포함한 running model을 유지합니다.
Honcho는 Memory Providers 시스템에 통합되어 있습니다. 아래의 모든 기능은 통합 memory provider interface를 통해 사용할 수 있습니다.
Honcho가 추가하는 것
| 기능 | Built-in Memory | Honcho |
|---|---|---|
| Cross-session persistence | ✔ file-based MEMORY.md/USER.md | ✔ API 기반 server-side 저장 |
| 사용자 profile | ✔ agent가 수동으로 정리 | ✔ 자동 dialectic reasoning |
| 세션 요약 | — | ✔ session-scoped context injection |
| Multi-agent isolation | — | ✔ peer별 profile 분리 |
| Observation mode | — | ✔ unified 또는 directional observation |
| Conclusion(파생 insight) | — | ✔ pattern에 대한 server-side reasoning |
| history 검색 | ✔ FTS5 session search | ✔ conclusion semantic search |
Dialectic reasoning: 각 대화 턴 뒤(dialecticCadence로 제어), Honcho는 대화 내용을 분석해 사용자의 선호, 습관, 목표에 대한 insight를 도출합니다. 이 insight는 시간이 지날수록 축적되어, 사용자가 명시적으로 말한 내용을 넘어 더 깊은 이해를 제공합니다. dialectic은 automatic cold/warm prompt selection과 함께 multi-pass depth(1-3 passes)를 지원합니다. cold start query는 일반적인 사용자 사실에 집중하고, warm query는 session-scoped context를 우선합니다.
Session-scoped context: base context에는 이제 user representation과 peer card뿐 아니라 session summary도 포함됩니다. agent는 현재 세션에서 이미 논의된 내용을 인식할 수 있으므로 반복을 줄이고 흐름을 이어갈 수 있습니다.
Multi-agent profiles: 여러 Hermes instance가 같은 사용자와 대화할 때(예: coding assistant와 personal assistant), Honcho는 별도의 "peer" profile을 유지합니다. 각 peer는 자신의 observation과 conclusion만 볼 수 있으므로 context가 서로 섞이는 것을 막습니다.
설정
hermes memory setup # select "honcho" from the provider list
또는 직접 설정합니다.
# ~/.hermes/config.yaml
memory:
provider: honcho
echo 'HONCHO_API_KEY=***' >> ~/.hermes/.env
API key는 honcho.dev에서 받을 수 있습니다.
아키텍처
Two-Layer Context Injection
매 턴마다(hybrid 또는 context mode에서) Honcho는 system prompt에 주입할 context를 두 layer로 조립합니다.
- Base context - session summary, user representation, user peer card, AI self-representation, AI identity card.
contextCadence에 맞춰 refresh됩니다. "이 사용자가 누구인가" layer입니다. - Dialectic supplement - 사용자의 현재 상태와 필요에 대해 LLM이 합성한 reasoning.
dialecticCadence에 맞춰 refresh됩니다. "지금 무엇이 중요한가" layer입니다.
두 layer는 이어 붙인 뒤, contextTokens budget이 설정되어 있으면 그 한도에 맞게 truncate됩니다.
Cold/Warm Prompt Selection
dialectic은 두 가지 prompt strategy 중 하나를 자동으로 선택합니다.
- Cold start(아직 base context 없음): 일반 query - "이 사람은 누구인가? 선호, 목표, 작업 스타일은 무엇인가?"
- Warm session(base context 있음): session-scoped query - "지금까지 이 세션에서 논의된 내용을 기준으로, 이 사용자에 대해 가장 관련 있는 context는 무엇인가?"
base context가 채워졌는지에 따라 자동으로 결정됩니다.
서로 독립적인 세 가지 설정 knob
비용과 깊이는 서로 독립적인 세 가지 knob으로 제어합니다.
| Knob | 제어 대상 | 기본값 |
|---|---|---|
contextCadence | context() API call 사이의 turn 수(base layer refresh) | 1 |
dialecticCadence | peer.chat() LLM call 사이의 turn 수(dialectic layer refresh) | 2(권장 1-5) |
dialecticDepth | dialectic invocation마다 실행할 .chat() pass 수(1-3) | 1 |
이 값들은 서로 독립적입니다. context refresh는 자주 하면서 dialectic은 드물게 실행할 수도 있고, 낮은 빈도로 deep multi-pass dialectic을 실행할 수도 있습니다. 예를 들어 contextCadence: 1, dialecticCadence: 5, dialecticDepth: 2는 base context를 매 턴 refresh하고, dialectic은 5턴마다 실행하며, 각 dialectic run은 2 pass를 수행합니다.
Dialectic Depth(Multi-Pass)
dialecticDepth가 1보다 크면 각 dialectic invocation은 여러 .chat() pass를 실행합니다.
- Pass 0: cold 또는 warm prompt(위 설명 참고)
- Pass 1: self-audit - 초기 평가의 빈틈을 찾아내고 최근 세션의 evidence를 합성합니다.
- Pass 2: reconciliation - 이전 pass 사이의 모순을 확인하고 최종 synthesis를 생성합니다.
각 pass는 비례적인 reasoning level을 사용합니다. 초기 pass는 더 가볍게, main pass는 base level로 실행됩니다. pass별 level은 dialecticDepthLevels로 override할 수 있습니다. 예를 들어 depth-3 run에는 ["minimal", "medium", "high"]를 사용할 수 있습니다.
이전 pass가 강한 signal(길고 구조화된 output)을 반환하면 이후 pass는 early bail-out합니다. 따라서 depth 3이 항상 LLM call 3번을 의미하지는 않습니다.
세션 시작 Prewarm
세션이 초기화될 때 Honcho는 설정된 전체 dialecticDepth로 background dialectic call을 실행하고, 그 결과를 turn 1의 context assembly에 직접 넘깁니다. cold peer에서 single-pass prewarm은 얕은 output만 반환하는 경우가 많습니다. multi-pass depth는 사용자가 말하기 전부터 audit/reconcile cycle을 실행합니다. prewarm 결과가 turn 1까지 도착하지 않으면, turn 1은 bounded timeout이 있는 synchronous call로 fallback합니다.
Query-Adaptive Reasoning Level
자동 주입되는 dialectic은 query length에 따라 dialecticReasoningLevel을 조정합니다. 120자 이상이면 +1 level, 400자 이상이면 +2 level을 적용하고, reasoningLevelCap(기본값 "high")에서 clamp합니다. 모든 자동 call을 dialecticReasoningLevel에 고정하려면 reasoningHeuristic: false를 사용하세요. 사용 가능한 level은 minimal, low, medium, high, max입니다.
설정 옵션
Honcho는 ~/.honcho/config.json(global) 또는 $HERMES_HOME/honcho.json(profile-local)에서 설정합니다. setup wizard가 이 과정을 대신 처리합니다.
전체 config reference
| Key | 기본값 | 설명 |
|---|---|---|
contextTokens | null(uncapped) | 턴마다 자동 주입되는 context의 token budget. 정수(예: 1200)를 설정하면 cap이 걸립니다. word boundary에서 truncate됩니다. |
contextCadence | 1 | context() API call 사이의 최소 turn 수(base layer refresh) |
dialecticCadence | 2 | peer.chat() LLM call 사이의 최소 turn 수(dialectic layer). 권장 1-5. tools mode에서는 model이 직접 call하므로 무관합니다. |
dialecticDepth | 1 | dialectic invocation마다 실행할 .chat() pass 수. 1-3으로 clamp됩니다. |
dialecticDepthLevels | null | pass별 reasoning level의 optional array. 예: ["minimal", "low", "medium"]. 비례 기본값을 override합니다. |
dialecticReasoningLevel | 'low' | base reasoning level: minimal, low, medium, high, max |
dialecticDynamic | true | true이면 model이 tool param을 통해 call별 reasoning level을 override할 수 있습니다. |
dialecticMaxChars | 600 | system prompt에 주입되는 dialectic result의 최대 문자 수 |
recallMode | 'hybrid' | hybrid(auto-inject + tools), context(inject only), tools(tools only) |
writeFrequency | 'async' | message flush 시점: async(background thread), turn(sync), session(batch on end), 또는 정수 N |
saveMessages | true | message를 Honcho API에 persist할지 여부 |
observationMode | 'directional' | directional(all on) 또는 unified(shared pool). 세밀하게 제어하려면 observation object로 override합니다. |
messageMaxChars | 25000 | add_messages()로 전송되는 message당 최대 문자 수. 초과하면 chunk됩니다. |
dialecticMaxInputChars | 10000 | peer.chat()에 들어가는 dialectic query input의 최대 문자 수 |
sessionStrategy | 'per-directory' | per-directory, per-repo, per-session, 또는 global |
Session strategy는 Honcho session이 작업에 매핑되는 방식을 제어합니다.
per-session-hermes실행마다 새 session을 사용합니다. clean start이며 memory는 tool을 통해 접근합니다. 새 사용자에게 권장됩니다.per-directory- working directory마다 하나의 Honcho session을 사용합니다. context가 여러 실행에 걸쳐 축적됩니다.per-repo- git repository마다 하나의 session을 사용합니다.global- 모든 directory에서 하나의 session을 공유합니다.
Recall mode는 memory가 대화로 들어오는 방식을 제어합니다.
hybrid- context를 system prompt에 자동 주입하고 tools도 제공합니다. model이 query 시점을 결정합니다.context- 자동 주입만 사용하고 tools는 숨깁니다.tools- tools만 사용하고 자동 주입은 하지 않습니다. agent가honcho_reasoning,honcho_search등을 명시적으로 호출해야 합니다.
recall mode별 setting:
| Setting | hybrid | context | tools |
|---|---|---|---|
writeFrequency | message flush | message flush | message flush |
contextCadence | base context refresh gate | base context refresh gate | 무관 - injection 없음 |
dialecticCadence | auto LLM call gate | auto LLM call gate | 무관 - model이 직접 call |
dialecticDepth | invocation마다 multi-pass | invocation마다 multi-pass | 무관 - model이 직접 call |
contextTokens | injection cap | injection cap | 무관 - injection 없음 |
dialecticDynamic | model override gate | N/A(tools 없음) | model override gate |
tools mode에서는 model이 완전히 제어합니다. 원할 때 honcho_reasoning을 호출하고, 원하는 reasoning_level을 선택합니다. cadence와 budget setting은 auto-injection이 있는 mode(hybrid, context)에만 적용됩니다.
Observation(Directional vs. Unified)
Honcho는 대화를 peer들이 message를 주고받는 구조로 모델링합니다. 각 peer에는 Honcho의 SessionPeerConfig에 1:1로 매핑되는 두 observation toggle이 있습니다.
| Toggle | 효과 |
|---|---|
observeMe | Honcho가 이 peer의 own messages로부터 해당 peer의 representation을 만듭니다. |
observeOthers | 이 peer가 다른 peer의 message를 관찰합니다. cross-peer reasoning에 사용됩니다. |
두 peer × 두 toggle = 네 개의 flag입니다. observationMode는 이 flag들을 위한 shorthand preset입니다.
| Preset | User flags | AI flags | 의미 |
|---|---|---|---|
"directional"(기본값) | me: on, others: on | me: on, others: on | 완전한 상호 observation. cross-peer dialectic을 활성화합니다. 즉 "사용자가 한 말과 AI의 응답을 기준으로 AI가 사용자에 대해 무엇을 아는가"를 reasoning합니다. |
"unified" | me: on, others: off | me: off, others: on | shared-pool semantics. AI는 사용자 message만 관찰하고, user peer는 self-model만 수행합니다. single-observer pool입니다. |
preset 대신 명시적인 observation block으로 peer별 제어를 override할 수 있습니다.
"observation": {
"user": { "observeMe": true, "observeOthers": true },
"ai": { "observeMe": true, "observeOthers": false }
}
일반적인 pattern:
| 의도 | Config |
|---|---|
| 전체 observation(대부분의 사용자) | "observationMode": "directional" |
| AI가 자신의 reply로 사용자를 다시 모델링하지 않게 함 | "ai": {"observeMe": true, "observeOthers": false} |
| 강한 persona를 가진 AI peer가 self-observation으로 업데이트되지 않게 함 | "ai": {"observeMe": false, "observeOthers": true} |
Honcho dashboard에서 설정한 server-side toggle은 local default보다 우선합니다. Hermes는 session init 때 이를 다시 sync합니다.
도구
Honcho가 memory provider로 활성화되어 있으면 다섯 가지 tool을 사용할 수 있습니다.
| Tool | 목적 |
|---|---|
honcho_profile | peer card를 읽거나 업데이트합니다. 업데이트하려면 card(fact list)를 전달하고, 읽기만 하려면 생략합니다. |
honcho_search | context에 대한 semantic search. LLM synthesis 없이 raw excerpt를 반환합니다. |
honcho_context | 전체 session context. summary, representation, card, recent messages를 포함합니다. |
honcho_reasoning | Honcho의 LLM이 합성한 답변. reasoning_level(minimal/low/medium/high/max)을 전달해 깊이를 제어합니다. |
honcho_conclude | conclusion을 생성하거나 삭제합니다. 생성하려면 conclusion, 삭제하려면 delete_id를 전달합니다(PII only). |
CLI 명령
hermes honcho subcommand는 Honcho가 active memory provider일 때만 등록됩니다. (config.yaml의 memory.provider: honcho) 먼저 hermes memory setup을 실행하고 Honcho를 선택하세요. 다음 invocation부터 subcommand가 나타납니다.
hermes honcho status # Connection status, config, and key settings
hermes honcho setup # Redirects to `hermes memory setup`
hermes honcho strategy # Show or set session strategy (per-session/per-directory/per-repo/global)
hermes honcho peer # Show or update peer names + dialectic reasoning level
hermes honcho mode # Show or set recall mode (hybrid/context/tools)
hermes honcho tokens # Show or set token budget for context and dialectic
hermes honcho identity # Seed or show the AI peer's Honcho identity
hermes honcho sync # Sync Honcho config to all existing profiles
hermes honcho peers # Show peer identities across all profiles
hermes honcho sessions # List known Honcho session mappings
hermes honcho map # Map current directory to a Honcho session name
hermes honcho enable # Enable Honcho for the active profile
hermes honcho disable # Disable Honcho for the active profile
hermes honcho migrate # Step-by-step migration guide from openclaw-honcho
hermes honcho에서 마이그레이션
이전에 standalone hermes honcho setup을 사용했다면:
- 기존 configuration(
honcho.json또는~/.honcho/config.json)은 보존됩니다. - server-side data(memory, conclusion, user profile)는 그대로 유지됩니다.
- 다시 활성화하려면
config.yaml에memory.provider: honcho를 설정합니다.
다시 login하거나 setup할 필요는 없습니다. hermes memory setup을 실행하고 "honcho"를 선택하면 wizard가 기존 config를 감지합니다.
전체 문서
전체 reference는 Memory Providers - Honcho를 참고하세요.