Honcho: 시간에 따라 변화하는 사람, 에이전트, 그룹, 프로젝트 및 아이디어를 이해하는 상태 유지 에이전트(Stateful

Honcho는 시간에 따라 변화하는 사람, 에이전트, 그룹, 프로젝트 및 아이디어를 이해하는 상태 유지 에이전트(Stateful Agents)를 구축하기 위한 메모리 인프라입니다.

메시지와 이벤트를 저장하고, Honcho가 백그라운드에서 추론(Reasoning)하게 한 다음, 어떤 모델이나 프레임워크로부터도 피어 표현(Peer Representations), 세션 컨텍스트(Session Context), 검색 결과 또는 자연어 통찰(Natural-language insights)을 쿼리(Query)하세요. api.honcho.dev에서 관리형으로 사용하거나 FastAPI 서버를 직접 셀프 호스팅(Self-host)할 수 있습니다.

Honcho를 메모리 시스템으로 사용하면 에이전트의 유지력(Retention)을 높이고 더 큰 신뢰를 얻을 수 있으며, 기존 업체들을 압도할 수 있는 데이터 해자(Data moats)를 구축하는 데 도움이 됩니다.

Honcho는 에이전트 메모리(Agent Memory)의 파레토 프런티어(Pareto Frontier)를 정의했습니다. 자세한 내용은 영상을 시청하고, 평가(Evals) 페이지를 확인하며, 블로그 포스트를 읽어보세요.

• 시작하기 (Start Here)
• 왜 Honcho인가 (Why Honcho)
• Honcho 루프 (The Honcho Loop)
• 퀵스타트 (Quickstart)
• Honcho가 제공하는 것 (What Honcho Gives You)
• 통합 (Integrations)
• 핵심 개념 (Core Concepts)
• 벤치마크 및 평가 (Benchmarks & Evals)
• 셀프 호스팅 (Self-hosting)
• 설정 (Configuration)
• 아키텍처 (Architecture)
• SDK
• 더 알아보기 (Learn More)
• 기여하기 (Contributing)
• 라이선스 (License)

Honcho 프로젝트는 여러 저장소로 나뉘어 있으며, 이 저장소는 FastAPI 서버로 구현된 핵심 서비스 로직을 호스팅합니다. Python 및 TypeScript용 클라이언트 SDK는 sdks/ 디렉토리에 있습니다.

내가 하고 싶은 것...	경로	시작하기
코딩 에이전트에게 지속적인 메모리 부여	Claude Code, OpenCode, OpenClaw, Hermes 또는 모든 MCP 클라이언트	통합 (Integrations)
...
기능	의미
---	---
추론 우선 메모리 (Reasoning-first memory)	단순히 청크(Chunks)를 매칭하는 것이 아니라, 대화와 이벤트로부터 결론을 추출합니다.
...

저장 (Store) — 대화, 이벤트, 문서 또는 도구 추적(Tool traces)을 세션의 메시지로 저장합니다. 추론 (Reason) — Honcho가 백그라운드에서 큐(Queue)를 처리하고 피어 표현(Peer representations)을 업데이트합니다. 쿼리 (Query) — Honcho에 컨텍스트, 검색 결과, 피어 표현 또는 자연어 답변을 요청합니다. 주입 (Inject) — 결과를 모든 LLM 호출 또는 에이전트 프레임워크에 넣습니다.

구체적으로: 워크스페이스(Workspaces)는 피어(Peers)를 보유하고, 피어는 세션(Sessions)에 참여하며, 메시지는 세션에 존재합니다. 그리고 Honcho는 채팅 엔드포인트(Chat Endpoint)를 통해 쿼리하거나 직접 쿼리할 수 있는 피어별 표현(Per-peer representation)을 구축합니다.

app.honcho.dev에서 API 키를 받으세요 — 가입 시 조직(organization)에 참여하라는 안내가 표시되며, 각 조직은 전용 Honcho 인스턴스와 $100의 무료 크레딧을 받게 됩니다. 또는 셀프 호스팅(self-host)하여 http://localhost:8000에서 실행할 수도 있습니다.

pip install honcho-ai
# 또는: uv add honcho-ai
# 또는: poetry add honcho-ai

import os
from honcho import Honcho
# 관리형 서비스(Managed service)는 기본적으로 api.honcho.dev를 사용합니다. 셀프 호스팅의 경우, 다음을 전달하세요
...

npm install @honcho-ai/sdk
# 또는: bun add @honcho-ai/sdk

import { Honcho } from "@honcho-ai/sdk";
import OpenAI from "openai";
const honcho = new Honcho({
...

참고: 백그라운드 추론(background reasoning)은 비동기(asynchronous)로 이루어집니다. 새로 추가된 메시지가 채팅/표현(chat/representation) 응답에 반영되기까지 잠시 시간이 걸릴 수 있습니다. 낮은 지연 시간(low-latency)의 읽기가 필요한 경우, representation 엔드포인트를 사용하세요.

필요 사항	API
상호작용 기록 저장	session.add_messages(...)
...
전체 SDK 레퍼런스(SDK Reference) 및 API 레퍼런스(API Reference)를 확인하세요.

얼마나 깊게 통합할지에 따라 두 가지 방법이 있습니다:

플러그인 (더 풍부한 통합 — Claude Code 사용자에게 권장):

/plugin marketplace add plastic-labs/claude-honcho
/plugin install honcho@honcho

Raw MCP (모든 MCP 클라이언트 — Cursor, Cline, Windsurf 등에서 작동):

claude mcp add honcho \
--transport http \
--url "https://mcp.honcho.dev" \
...

상세 정보: Claude Code 가이드 · MCP 가이드.

opencode plugin "@honcho-ai/opencode-honcho" --global

상세 정보: OpenCode 가이드.

openclaw plugins install @honcho-ai/openclaw-honcho
openclaw honcho setup
openclaw gateway --force

openclaw honcho setup

API 키를 요청하고, 설정을 작성하며, 선택적으로 기존의 MEMORY.md, / USER.md, / IDENTITY.md 파일들을 Honcho로 마이그레이션(migrate)합니다 (비파괴적 방식 — 원본은 절대 삭제되지 않습니다). 상세 정보: OpenClaw 가이드.

hermes memory setup # "honcho"를 선택하고, api.honcho.dev 또는 로컬 서버를 지정하세요

상세 정보: Hermes 가이드.

기존 애플리케이션에 Honcho SDK를 연결하려면, 통합 스킬 (integration skill)을 설치하세요. 이 스킬은 코드베이스를 탐색하고, 통합 선호도를 질문하며, SDK 설정을 생성하고, 정상 작동 여부를 확인합니다:

npx skills add plastic-labs/honcho

그 다음 Claude Code에서 /honcho-integration을 호출하거나 (플러그인 마켓플레이스를 통해 /honcho-dev:integrate를 호출하세요).

상세 정보: 에이전트 중심 개발 가이드 (agentic development guide).

동일한 claude mcp add 양식(또는 클라이언트별 대응 양식)은 모든 MCP 호환 클라이언트에서 작동합니다. MCP 가이드를 참조하세요.

Honcho는 모든 것을 **피어 (peers)**를 중심으로 구성합니다. 인간과 AI 에이전트 모두가 일급 객체 (first-class entities)입니다. 피어 모델은 다음을 가능하게 합니다:

• 인간과 AI 에이전트가 혼합된 다자간 세션 (Multi-participant sessions)
• 구성 가능한 관찰 설정 (어떤 피어가 다른 피어를 관찰할지 설정)
• 모든 참여자를 위한 유연한 신원 관리 (identity management)
• 복잡한 멀티 에이전트 상호작용 (multi-agent interactions) 지원

피어들은 세션 내에서 메시지를 교환하며, Honcho는 해당 메시지들을 추론하여 사용자가 질의할 수 있는 각 피어의 표현 (representation)을 구축합니다.

워크스페이스 (Workspace) (이전 명칭: App): 최상위 컨테이너; 사용 사례(use cases) 간의 데이터를 격리합니다.
피어 (Peer) (이전 명칭: User): 모든 참여자 — 인간 사용자 또는 AI 에이전트.
세션 (Session): 대화 문맥 (conversation context); 피어들과의 다대다 (many-to-many) 관계.
메시지 (Message): 원자적 데이터 단위 (피어 간 통신 또는 수집된 문서 청크 (document chunk)).

Honcho에서 질의할 수 있는 항목:

결론 (Conclusions) — Honcho가 피어에 대해 추출한 내용 (연역적 및 귀납적). conclusions API를 통해 제공됩니다.
표현 (Representations) — Honcho가 피어에 대해 알고 있는 내용의 정적이고 저지연인 스냅샷 (선택적으로 세션 범위로 제한 가능).
피어 카드 (Peer Cards) — 간결한 신원 요약.
세션 문맥 / 요약 (Session context / summaries) — 장기 실행되는 대화를 위해 프롬프트에 즉시 사용 가능한 번들.

내부 저장소 (컬렉션 및 문서)

내부적으로 Honcho는 피어 관련 관찰 내용을 벡터 임베딩 (vector-embedded)된 **문서 (documents)**의 컬렉션 (collections) 형태로 저장합니다. 컬렉션은 (관찰자, 관찰 대상) 피어 쌍을 키(key)로 사용합니다 — 동일한 메커니즘이 자기 표현 (self-representation, observer == observed)을 지원합니다.

) 및 교차 피어 모델링 (cross-peer modelling, 피어 X가 피어 Y를 이해하는 방식). 이러한 프리미티브 (primitives)들은 직접적으로 노출되지 않으며, Conclusions API가 공개된 인터페이스 (public surface) 역할을 합니다.

Honcho의 평가 (evals) 범위는 LongMemEval, LoCoMo 및 기타 긴 대화 벤치마크 (long-conversation benchmarks)를 아우릅니다. 방법론과 재현 가능한 결과에 대해서는 평가 (evals) 페이지, 연구 블로그 포스트, 그리고 파레토 프런티어 (Pareto-frontier) 발표 영상을 참조하십시오.

Honcho는 AGPL-3.0 라이선스 하에 오픈 소스 (open source)로 제공됩니다. Docker를 사용하여 로컬에서 전체 서버를 실행한 다음, SDK를 http://localhost:8000으로 지정할 수 있습니다.

git clone https://github.com/plastic-labs/honcho.git
cd honcho
cp docker-compose.yml.example docker-compose.yml
...

그 다음 SDK를 해당 주소로 지정하십시오:

honcho = Honcho(workspace_id="my-app-testing", base_url="http://localhost:8000")
# 또는: export HONCHO_URL=http://localhost:8000

Docker 없는 로컬 개발

아래는 Docker 없이 Honcho 서버를 실행하기 위한 로컬 환경 설정 가이드입니다.

Honcho는 Python과 uv를 사용하여 개발되었습니다.

최소 Python 버전은 3.10입니다.

최소 uv 버전은 0.5.0입니다.

시스템에 종속성 (dependencies)이 설치되면, 다음 단계에 따라 로컬 프로젝트 설정을 완료하십시오.

저장소 클론 (Clone the repository)

git clone https://github.com/plastic-labs/honcho.git

저장소 진입 및 Python 종속성 설치

동일한 시스템의 다른 프로젝트로부터 Honcho의 종속성을 격리하기 위해 가상 환경 (virtual environment)을 사용하는 것을 권장합니다. 프로젝트에서 종속성을 동기화할 때 uv가 가상 환경을 생성할 것입니다.

cd honcho
uv sync

이렇게 하면 가상 환경이 생성되고 Honcho를 위한 종속성이 설치됩니다.
기본 가상 환경은 honcho/.venv에 위치합니다. 다음 명령을 통해 가상 환경을 활성화하십시오:

source honcho/.venv/bin/activate

데이터베이스 설정

Honcho는 pgvector가 포함된 Postgres를 데이터베이스로 사용합니다. Postgres 데이터베이스를 시작하는 쉬운 방법은 Supabase로 프로젝트를 생성하는 것입니다.

또는, docker-compose

샘플 데이터베이스 설정이 포함된 docker-compose 템플릿을 사용할 수 있습니다.
Docker를 사용하려면:

cp docker-compose.yml.example docker-compose.yml
docker compose up -d database

환경 변수(environment variables) 편집

Honcho는 런타임 환경 변수 (runtime environment variables) 관리를 위해 .env 파일을 사용합니다. 편의를 위해 .env.template 파일이 포함되어 있습니다. 여러 설정 중 일부는 필수 사항이 아니며, 추가적인 로깅 (logging), 모니터링 (monitoring) 및 보안 (security)을 위해서만 필요합니다.

필수 설정 사항은 다음과 같습니다:

DB_CONNECTION_URI= # postgres 데이터베이스를 위한 연결 URI (postgresql+psycopg 접두사 포함)
# LLM 제공자 API 키
LLM_GEMINI_API_KEY= # Google Gemini를 위한 API 키 (기본적으로 deriver, summary, 그리고 dialectic minimal/low 용도로 사용됨)
...

DB_CONNECTION_URI가 제대로 작동하려면 반드시 postgresql+psycopg 접두사가 있어야 함에 유의하십시오. 이는 sqlalchemy에 의한 요구 사항입니다.

템플릿은 추가 기능이 기본적으로 비활성화되어 있습니다. 기능이 비활성화되었는지 확인하려면 다음 환경 변수들이 false로 설정되어 있는지 확인하면 됩니다:

AUTH_USE_AUTH=false
SENTRY_ENABLED=false

만약 AUTH_USE_AUTH를 true로 설정하면 JWT 비밀키 (JWT secret)를 생성해야 합니다. 다음 명령어로 생성할 수 있습니다:

python scripts/generate_jwt_secret.py

이 명령은 JWT 비밀키를 생성하여 콘솔에 출력합니다. 그런 다음 AUTH_JWT_SECRET 환경 변수를 설정할 수 있습니다. 이는 AUTH_USE_AUTH를 위해 필수적입니다:

AUTH_JWT_SECRET=<generated_secret>

데이터베이스 마이그레이션 (database migrations) 실행

데이터베이스 설정과 환경 변수 구성이 완료되면, 마이그레이션을 실행하여 필요한 테이블을 생성하십시오:

uv run alembic upgrade head

이 명령은 워크스페이스 (workspaces), 피어 (peers), 세션 (sessions), 메시지 (messages) 및 큐 시스템 (queue system)을 포함하여 Honcho에 필요한 모든 테이블을 생성합니다.

Honcho 실행

모든 설정이 완료되었으므로 이제 Honcho의 로컬 인스턴스를 실행할 수 있습니다. 데이터베이스 외에도 두 가지 컴포넌트 (components)가 실행 중이어야 합니다:

API 서버 시작:

uv run fastapi dev src/main.py

이것은 코드가 변경될 때마다 자동으로 재시작되는 개발 서버입니다.

백그라운드 워커 (deriver) 시작:

별도의 터미널에서 다음을 실행하세요:

uv run python -m src.deriver

deriver는 표현(representations), 요약(summaries), 피어 카드(peer cards)를 생성하고 드림(dreaming) 태스크를 관리합니다. 런타임 효율성을 높이기 위해 deriver의 수를 늘릴 수 있습니다.

기여자 (Contributors): pre-commit 설정을 보려면 CONTRIBUTING.md를 참조하세요. Fly.io 배포: Self-hosting docs → Deploying on Fly.io를 참조하세요.

Honcho는 TOML 파일과 환경 변수 (environment variables)를 모두 지원하는 유연한 설정 시스템을 사용합니다. 설정 값은 다음 우선순위에 따라 로드됩니다: 환경 변수 > .env 파일 > config.toml > 기본값 (defaults).

전체 설정 참조 (Full configuration reference)

시작하려면 예시 설정 파일을 복사하세요:

cp config.toml.example config.toml

그 다음 필요에 따라 값을 수정하세요. TOML 파일은 다음과 같은 섹션으로 구성됩니다:

[app]

• 애플리케이션 레벨 설정 (로그 레벨, 세션 제한, 임베딩 설정, 네임스페이스 (namespace))

[db]

• 데이터베이스 연결 및 풀 (pool) 설정

[auth]

• 인증 (Authentication) 설정

[cache]

• Redis 캐시 설정

[llm]

• LLM 제공자 API 키 및 일반 설정

[deriver]

• 백그라운드 워커 설정 및 표현 (representation) 설정

[peer_card]

• 피어 카드 (peer card) 생성 설정

[dialectic]

• 레벨별 추론 (reasoning) 설정이 포함된 채팅 엔드포인트 (Chat Endpoint) 설정

[summary]

• 세션 요약 (Session summarization) 설정

[dream]

• 드림 (Dream) 처리 설정 (전문가 모델 및 놀라움 (surprisal) 설정 포함)

[webhook]

• 웹훅 (Webhook) 설정

[metrics]

• Prometheus 풀 기반 (pull-based) 메트릭

[telemetry]

• 분석을 위한 CloudEvents 텔레메트리 (telemetry)

[vector_store]

• 벡터 스토어 (Vector store) 설정 (pgvector, turbopuffer, 또는 lancedb)

[sentry]

• 에러 추적 및 모니터링 설정

모든 설정 값은 환경 변수를 사용하여 재정의(override)할 수 있습니다. 환경 변수 이름은 다음 패턴을 따릅니다:

{SECTION}_{KEY}

• 최상위 섹션 설정의 경우
• {KEY} 내부에서는 __를 사용합니다.

중첩된 설정 (nested settings)의 경우
{KEY}

앱 레벨 설정 (app-level settings)의 경우

예시:

DB_CONNECTION_URI

• 데이터베이스 연결 문자열 (Database connection string)

AUTH_JWT_SECRET

• JWT 비밀 키 (JWT secret key)

DERIVER_MODEL_CONFIG__TRANSPORT

• 백그라운드 디라이버 (background deriver)를 위한 전송 (Transport)

SUMMARY_MODEL_CONFIG__MODEL

• 요약 모델 재정의 (Summary model override)

DIALECTIC_LEVELS__low__MODEL_CONFIG__MODEL

• 낮은 추론 레벨 (low reasoning level)을 위한 모델

LOG_LEVEL

• 애플리케이션 로그 레벨 (Application log level)

METRICS_ENABLED

• Prometheus 메트릭 (Prometheus metrics) 활성화

TELEMETRY_ENABLED

• CloudEvents 텔레메트리 (CloudEvents telemetry) 활성화

만약 config.toml에 다음과 같이 작성되어 있다면:

[db]
CONNECTION_URI = "postgresql+psycopg://localhost/honcho_dev"
POOL_SIZE = 10

프로덕션 (production) 환경에서 연결 URI (connection URI)만 재정의할 수 있습니다:

export DB_CONNECTION_URI="postgresql+psycopg://prod-server/honcho_prod"