Honcho 🐘

開源 AI 記憶與推理引擎 — 讓 AI 代理擁有持續學習、長期記憶與高階推理能力

📖 專案簡介

Honcho 是由 Plastic Labs 開發的開源 AI 記憶與推理基礎設施。它解決了 LLM 的核心限制：上下文視窗有限、無法長期記憶、缺乏狀態一致性。

核心價值主張

傳統 RAG 方案	Honcho 方案
靜態向量檢索，遺失語意脈絡	形式邏輯推理，提取潛在關聯與結論
手動調優分塊策略	自動化背景處理，免工程循環
無狀態對話，上下文截斷	持續學習系統，實體狀態隨時間演化
單一使用者模式	多參與者 (Peer) 混合會話

適用場景

✅ 長期對話助手：無限期延續對話，自動壓縮歷史上下文
✅ 高度個人化 AI：學習使用者偏好、行為模式、歷史互動
✅ 多智能體協作：協調多個 AI Agent 與人類的複雜互動
✅ RAG 知識管理：語意向量儲存與高維度上下文檢索
✅ 教育/辅导系統：追蹤學習進度、理解風格、知識盲點演化

🏗️ 架構設計

資料模型階層

Workspace (應用隔離容器)
├── Peer (實體：使用者/AI/物件/群組)
│   ├── Sessions (對話線程，多對多關係)
│   │   └── Messages (原子訊息單元)
│   ├── Representations (推理結論)
│   └── Collections (RAG 向量庫)
│       └── Documents (語意文件)

四大核心原語

原語	說明	範例
Workspace	頂層隔離容器，隔離不同應用或環境	`my-app-prod`、`my-app-staging`
Peer	持續存在的實體，統一抽象人類與 AI	`user:alice`、`agent:math-tutor`
Session	具有時間邊界的互動線程	`homework-help-2024-01`
Message	觸發推理的資料單元	對話、事件、文件、活動日誌

推理架構

[寫入 Messages] → [觸發背景管線] → [推理模型分析]
                                      ↓
                        [處理矛盾 → 提取關聯 → 更新 Representations]
                                      ↓
                        [查詢時返回高維上下文 → 增強 LLM 回應]

關鍵設計理念：以「推理結論 (Representations)」取代「原始對話檢索」，解決傳統 RAG 的脈絡遺失與自我矛盾問題。

🚀 快速開始

選項 1️⃣：使用託管服務（最簡單）

# 1. 註冊帳號（含 $100 試用額度）
# 前往 https://app.honcho.dev 註冊

# 2. 安裝 Python SDK
pip install honcho-ai

# 3. 開始使用

from honcho import Honcho

# 初始化客戶端（使用託管服務）
honcho = Honcho(workspace_id="my-app")

# 建立實體與對話
alice = honcho.peer("alice")
session = honcho.session("session-1")
session.add_messages([alice.message("幫我檢查數學作業")])

# 取得壓縮後的上下文（傳給 LLM）
context = session.context(summary=True, tokens=10_000)

# 查詢實體見解（自然語言提問）
response = alice.chat("該使用者偏好哪種學習方式？")

# 語意搜尋
results = alice.search("數學作業")

選項 2️⃣：本地開發部署

系統需求

Python ≥ 3.10
uv ≥ 0.5.0（安裝指南）
PostgreSQL 14+（需 pgvector 擴充功能）
至少一個 LLM API Key（Gemini/Anthropic/OpenAI/Groq）

安裝步驟

1. 取得原始碼與安裝依賴

git clone https://github.com/plastic-labs/honcho.git
cd honcho
uv sync  # 自動建立 .venv 虛擬環境

2. 啟動資料庫

# 方式 A：使用 Docker Compose（推薦）
cp docker-compose.yml.example docker-compose.yml
docker compose up -d database

# 方式 B：使用 Supabase 雲端 PostgreSQL
# 前往 https://supabase.com 建立專案，取得 Connection URI

3. 設定環境變數

cp .env.template .env

編輯 .env 檔案，必填欄位：

# 資料庫連線（必須包含 postgresql+psycopg 前綴）
DB_CONNECTION_URI=postgresql+psycopg://user:password@localhost:5432/honcho

# LLM API Keys（至少填寫一個）
LLM_GEMINI_API_KEY=your-gemini-key
LLM_ANTHROPIC_API_KEY=your-anthropic-key
LLM_OPENAI_API_KEY=your-openai-key
LLM_GROQ_API_KEY=your-groq-key

4. 執行資料庫遷移

uv run alembic upgrade head

此步驟會建立以下資料表：

workspaces — 工作空間
peers — 實體
sessions — 對話線程
messages — 訊息記錄
representations — 推理結論
collections / documents — 向量知識庫

5. 啟動服務

需要啟動 兩個進程：

# 終端 1：啟動 API 伺服器
uv run fastapi dev src/main.py

# 終端 2：啟動背景推理 Worker
uv run python -m src.deriver

啟動後，存取 API 文件：

Swagger UI：http://localhost:8000/docs
ReDoc：http://localhost:8000/redoc

選項 3️⃣：Docker 一鍵部署

# 1. 複製 Docker Compose 設定
cp docker-compose.yml.example docker-compose.yml

# 2. 編輯 .env 檔案（同上）

# 3. 啟動所有服務
docker compose up -d

# 4. 執行資料庫遷移
docker compose exec api uv run alembic upgrade head

選項 4️⃣：部署至 Fly.io

# 1. 匯入環境變數
cat .env | flyctl secrets import

# 2. 部署
flyctl deploy

📚 核心功能詳解

1. Peer（實體管理）

Peer 是 Honcho 的核心抽象，將使用者、AI 代理、物件、群組統一建模為「持續存在的實體」。

# 建立或取得 Peer
alice = honcho.peer("alice")
tutor_agent = honcho.peer("math-tutor", peer_type="agent")

# 自然語言對話（查詢 Peer 的洞察）
response = alice.chat("這個使用者最近的學習進度如何？")

# 搜尋相關訊息
results = alice.search("代數方程式")

# 取得靜態洞察文件（低延遲，用於 Prompt 增強）
representation = session.representation(alice)

Chat API 進階用法

# 自訂系統提示
response = alice.chat(
    "分析這個使用者的行為模式",
    system_prompt="你是一個專業的學習分析師"
)

# 限制上下文範圍
response = alice.chat(
    "最近表現如何？",
    session_filter=lambda s: s.created_at > "2024-01-01"
)

2. Session（對話線程）

Session 管理具有時間邊界的互動，支援多參與者混合對話。

# 建立 Session
session = honcho.session("math-homework-jan")

# 新增訊息（支援批量）
session.add_messages([
    alice.message("我不懂二次方程式怎麼解"),
    tutor_agent.message("讓我一步一步教你..."),
    alice.message("為什麼第一步要這樣做？"),
])

# 取得壓縮後的上下文（OpenAI 格式）
context = session.context(
    summary=True,        # 包含自動生成的摘要
    tokens=10_000,       # 限制 Token 用量
    peer=alice           # 針對特定 Peer 過濾
)

# 傳給 LLM 使用
from openai import OpenAI
client = OpenAI()
response = client.chat.completions.create(
    model="gpt-4",
    messages=context + [{"role": "user", "content": "繼續解釋"}]
)

多參與者對話

# 建立多人會話
group_session = honcho.session("study-group")

# 多個 Peer 同時互動
group_session.add_messages([
    alice.message("我覺得這題答案是 C"),
    bob.message("但我算出來是 B"),
    tutor_agent.message("讓我們一起驗證一下...")
])

# Honcho 自動追蹤每個 Peer 的狀態與關係

3. Context 提取（智能壓縮）

Honcho 的核心競爭力：將冗長歷史壓縮為高品質上下文。

# 基礎用法
context = session.context(summary=True, tokens=5000)

# 進階參數
context = session.context(
    summary=True,           # 啟用摘要生成
    tokens=10_000,          # 最大 Token 限制
    peer=alice,             # 針對特定 Peer 優化
    include_metadata=True,  # 包含元資料
    format="openai"         # 輸出格式（預設 OpenAI 格式）
)

# 回傳格式範例
# [
#   {"role": "system", "content": "使用者 Alice 的摘要：..."},
#   {"role": "user", "content": "歷史對話壓縮版..."},
#   ...
# ]

4. Representation（推理結論）

Representation 是 Honcho 推理管線的產出，取代傳統向量檢索。

# 取得 Peer 的推理結論（低延遲）
representation = session.representation(alice)

# 內容包含：
# - 學習風格與偏好
# - 知識盲點與誤解模式
# - 歷史互動總結
# - 行為趨勢預測

# 用於 Prompt 增強
prompt = f"""
基於以下使用者洞察，提供個人化回應：

{representation}

使用者問題：{user_question}
"""

5. Collection（向量知識庫）

內建 RAG 支援，儲存與檢索語意向量。

# 建立 Collection
math_knowledge = honcho.collection("algebra-basics")

# 新增文件
math_knowledge.add_document(
    content="二次方程式公式：x = (-b ± √(b²-4ac)) / 2a",
    metadata={"topic": "quadratic", "difficulty": "intermediate"}
)

# 語意搜尋
results = math_knowledge.search("如何解 ax²+bx+c=0")

# Peer 關聯的 Collection（個人化知識庫）
alice_math = alice.collection("my-math-notes")

6. Deriver（背景推理 Worker）

Deriver 是非同步處理進程，負責：

✅ 提取 Representations（推理結論）
✅ 生成 Session Summaries（對話摘要）
✅ 管理向量索引更新
✅ 處理 Dreaming 任務（深度推理）

# 啟動 Deriver
uv run python -m src.deriver

# 监控队列状态（通过 API）
# GET /deriver/status

配置選項（在 .env 中）：

# 推理深度控制
DERIVER_BATCH_SIZE=100        # 批次處理大小
DERIVER_INTERVAL=60           # 處理間隔（秒）
DERIVER_MAX_CONCURRENT=5      # 最大並行任務數

🔌 SDK 參考

Python SDK

pip install honcho-ai
# 或
uv add honcho-ai
# 或
poetry add honcho-ai

完整初始化

from honcho import Honcho, AsyncHoncho

# 同步客戶端
honcho = Honcho(
    workspace_id="my-app",
    base_url="http://localhost:8000",  # 本地開發
    api_key="your-api-key"             # 託管服務需要
)

# 非同步客戶端
async_honcho = AsyncHoncho(
    workspace_id="my-app",
    base_url="http://localhost:8000"
)

核心 API 速查表

方法	說明	回傳類型
`honcho.peer(peer_id)`	取得/建立 Peer	`Peer`
`honcho.session(session_id)`	取得/建立 Session	`Session`
`honcho.collection(name)`	取得/建立 Collection	`Collection`
`peer.chat(query)`	自然語言洞察查詢	`ChatResponse`
`peer.search(query)`	語意搜尋	`SearchResults`
`session.add_messages([...])`	批量新增訊息	`None`
`session.context(summary, tokens)`	提取壓縮上下文	`List[Message]`
`session.representation(peer)`	取得推理結論	`str`
`collection.add_document(...)`	新增向量文件	`Document`
`collection.search(query)`	語意檢索	`List[Document]`

TypeScript SDK

npm install @honcho-ai/sdk
# 或
yarn add @honcho-ai/sdk

import { Honcho } from '@honcho-ai/sdk';

const honcho = new Honcho({
  workspaceId: 'my-app',
  baseUrl: 'http://localhost:8000',
  apiKey: 'your-api-key'
});

// 使用方式與 Python 類似
const alice = honcho.peer('alice');
const session = honcho.session('session-1');

await session.addMessages([
  { role: 'user', content: '幫我複習微積分' }
]);

const context = await session.context({ summary: true, tokens: 10000 });

🎯 實際應用範例

範例 1：個人化學習助手

from honcho import Honcho
from openai import OpenAI

honcho = Honcho(workspace_id="tutor-app")
openai = OpenAI()

def tutor_interaction(user_id: str, question: str):
    # 取得使用者與導師實體
    student = honcho.peer(f"student:{user_id}")
    tutor = honcho.peer("ai-math-tutor")
    
    # 建立或取得對話
    session = honcho.session(f"math-session-{user_id}")
    
    # 新增使用者問題
    session.add_messages([student.message(question)])
    
    # 取得個人化上下文（包含學習風格、歷史盲點）
    context = session.context(summary=True, tokens=8000, peer=student)
    
    # 呼叫 LLM
    response = openai.chat.completions.create(
        model="gpt-4",
        messages=context + [
            {"role": "system", "content": "你是耐心的數學老師，善用蘇格拉底式提問"},
            {"role": "user", "content": question}
        ]
    )
    
    # 記錄導師回應
    session.add_messages([tutor.message(response.choices[0].message.content)])
    
    return response.choices[0].message.content

# 使用範例
answer = tutor_interaction("alice", "為什麼負數乘負數會變正數？")
print(answer)

範例 2：使用者行為分析儀表板

def generate_user_report(user_id: str):
    user = honcho.peer(f"user:{user_id}")
    
    # 查詢多维度洞察
    learning_style = user.chat("這個使用者的學習風格是什麼？")
    progress = user.chat("最近的學習進度與趨勢如何？")
    weak_points = user.chat("有哪些知識盲點需要加強？")
    
    # 搜尋特定主題互動
    math_interactions = user.search("數學", limit=50)
    
    # 生成報告
    return {
        "learning_style": learning_style.content,
        "progress_summary": progress.content,
        "weak_points": weak_points.content,
        "recent_activity_count": len(math_interactions)
    }

範例 3：多智能體協調系統

def multi_agent_collaboration(task: str):
    # 建立專家團隊
    mathematician = honcho.peer("expert:math")
    physicist = honcho.peer("expert:physics")
    coordinator = honcho.peer("agent:coordinator")
    
    # 協作會話
    collab_session = honcho.session("research-collab")
    
    # 分配任務
    collab_session.add_messages([
        coordinator.message(f"請共同解決：{task}"),
        mathematician.message("從數學角度，這涉及..."),
        physicist.message("物理上對應的模型是..."),
    ])
    
    # 取得壓縮後的協作上下文
    context = collab_session.context(summary=True, tokens=15000)
    
    # 生成最終結論
    return openai.chat.completions.create(
        model="gpt-4",
        messages=context + [
            {"role": "system", "content": "整合上述討論，給出最終答案"}
        ]
    )

⚙️ 進階配置

配置系統優先級

Honcho 支援多種配置方式，優先級如下：

環境變數 > .env 檔案 > config.toml > 預設值

環境變數完整清單

變數	說明	預設值	必填
`DB_CONNECTION_URI`	PostgreSQL 連線字串	-	✅
`LLM_GEMINI_API_KEY`	Google Gemini API Key	-	選填*
`LLM_ANTHROPIC_API_KEY`	Anthropic API Key	-	選填*
`LLM_OPENAI_API_KEY`	OpenAI API Key	-	選填*
`LLM_GROQ_API_KEY`	Groq API Key	-	選填*
`REDIS_URL`	Redis 快取連線（選用）	-	❌
`DERIVER_BATCH_SIZE`	背景處理批次大小	`100`	❌
`DERIVER_INTERVAL`	處理間隔（秒）	`60`	❌
`LOG_LEVEL`	日誌層級	`INFO`	❌

*至少需要填寫一個 LLM API Key

向量儲存後端配置

Honcho 支援多種向量儲存方案：

# 選項 1：pgvector（預設，整合於 PostgreSQL）
VECTOR_STORE=pgvector

# 選項 2：Turbopuffer
VECTOR_STORE=turbopuffer
TURBOPUFFER_API_KEY=your-key

# 選項 3：LanceDB
VECTOR_STORE=lancedb
LANCEDB_URI=/path/to/db

效能調優參數

參數	影響	建議值
`tokens`（context）	上下文長度	`5000-15000`
`summary`（context）	是否生成摘要	`True`（長對話）
`DERIVER_MAX_CONCURRENT`	推理並行數	CPU 核心數 × 2
`batch_size`（search）	搜尋回傳筆數	`10-50`

🛠️ 開發者指南

程式碼品質工具

# 安裝 pre-commit 掛鉤
uv run pre-commit install

# 手動執行檢查
uv run pre-commit run --all-files

# 包含：Ruff（Python Lint）、Biome（TS Lint）、basedpyright（型別檢查）

資料庫遷移

# 建立新遷移
uv run alembic revision --autogenerate -m "描述變更"

# 執行遷移
uv run alembic upgrade head

# 回滾
uv run alembic downgrade -1

日誌與監控

# 查看 API 日誌
uv run fastapi dev src/main.py --log-level debug

# 查看 Deriver 日誌
uv run python -m src.deriver --verbose

# Prometheus 指標（若啟用）
# GET /metrics

測試

# 執行測試套件
uv run pytest

# 執行單一測試
uv run pytest tests/test_peer.py -v

# 產生涵蓋率報告
uv run pytest --cov=src --cov-report=html

📊 觀測性（Observability）

Honcho 整合了完整的觀測性堆疊：

元件	連接埠	用途
Grafana	3000	儀表板視覺化
Prometheus	9090	指標收集
Loki	3100	日誌聚合
Node Exporter	9100	系統指標
cAdvisor	8080	容器資源監控

啟動觀測性堆疊：

docker compose up -d grafana prometheus loki

🐛 疑難排解

常見問題

Q1: 資料庫連線失敗

# 檢查 PostgreSQL 是否運行
docker compose ps

# 確認 DB_CONNECTION_URI 格式正確
# 必須包含 postgresql+psycopg:// 前綴

Q2: Deriver 沒有處理任務

# 確認 Deriver 已啟動
uv run python -m src.deriver

# 檢查隊列狀態
# GET /deriver/status

# 查看日誌
uv run python -m src.deriver --verbose

Q3: Chat API 回應緩慢

檢查 LLM API Key 是否正確
調整 DERIVER_BATCH_SIZE 減少批次負載
啟用 Redis 快取（設定 REDIS_URL）
降低 tokens 參數減少上下文處理量

Q4: 向量搜尋不準確

確認 pgvector 擴充功能已安裝
檢查 Embedding 模型是否一致
調整搜尋相似度閾值

除錯模式

# 啟用詳細日誌
export LOG_LEVEL=DEBUG

# 查看完整堆疊追蹤
# API 錯誤會返回詳細的 JSON 回應
{
  "error": "ValidationError",
  "detail": "場位 peer_id 不能為空",
  "traceback": "..."
}

📚 學習資源

官方文件

📖 開發文件：docs.honcho.dev
🔌 API 參考：API Reference
📘 Python SDK：PyPI - honcho-ai
📗 TypeScript SDK：NPM - @honcho-ai/sdk
🎓 教學指南：Tutorial - SDK

社群與支援

💬 Discord：加入社群
🐛 Issue Tracker：GitHub Issues
📝 部落格：Plastic Labs Blog

🤝 貢獻指南

我們歡迎所有形式的貢獻！

貢獻流程

Fork 專案
建立功能分支：git checkout -b feature/amazing-feature
編寫程式碼與測試
執行程式碼檢查：uv run pre-commit run --all-files
提交 Pull Request

Git Commit 規範

遵循 Conventional Commits：

feat: 新增 Peer 搜尋過濾器
fix: 修復 context 壓縮邊界條件
docs: 更新 API 文件
refactor: 重構 Deriver 隊列邏輯

開發環境設定

# 1. Fork 並 Clone
git clone https://github.com/YOUR_USERNAME/honcho.git
cd honcho

# 2. 安裝依賴
uv sync

# 3. 安裝 pre-commit
uv run pre-commit install

# 4. 建立開發用 .env
cp .env.template .env
# 編輯 .env（使用本地測試用 API Keys）

# 5. 啟動服務
uv run fastapi dev src/main.py

📄 授權條款

本專案採用 Apache License 2.0 授權。

Copyright 2024 Plastic Labs

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

🙏 致謝

Plastic Labs 團隊：開發與維護此專案
FastAPI 社群：提供優秀的 Web 框架
pgvector 團隊：PostgreSQL 向量擴充功能
所有貢獻者：完整名單

⭐ 支援專案

如果這個專案對你有幫助，請給我們一個 ⭐️！

Made with ❤️ by Plastic Labs

Name		Name	Last commit message	Last commit date
Latest commit History 2 Commits
LICENSE		LICENSE
README.md		README.md

Folders and files

Latest commit

History

Repository files navigation

Honcho 🐘

📖 專案簡介

核心價值主張

適用場景

🏗️ 架構設計

資料模型階層

四大核心原語

推理架構

🚀 快速開始

選項 1️⃣：使用託管服務（最簡單）

選項 2️⃣：本地開發部署

系統需求

安裝步驟

選項 3️⃣：Docker 一鍵部署

選項 4️⃣：部署至 Fly.io

📚 核心功能詳解

1. Peer（實體管理）

Chat API 進階用法

2. Session（對話線程）

多參與者對話

3. Context 提取（智能壓縮）

4. Representation（推理結論）

5. Collection（向量知識庫）

6. Deriver（背景推理 Worker）

🔌 SDK 參考

Python SDK

完整初始化

核心 API 速查表

TypeScript SDK

🎯 實際應用範例

範例 1：個人化學習助手

範例 2：使用者行為分析儀表板

範例 3：多智能體協調系統

⚙️ 進階配置

配置系統優先級

環境變數完整清單

向量儲存後端配置

效能調優參數

🛠️ 開發者指南

程式碼品質工具

資料庫遷移

日誌與監控

測試

📊 觀測性（Observability）

🐛 疑難排解

常見問題

除錯模式

📚 學習資源

官方文件

社群與支援

🤝 貢獻指南

貢獻流程

Git Commit 規範

開發環境設定

📄 授權條款

🙏 致謝

⭐ 支援專案

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Packages