---
name: Plasticlabs
description: Use when building stateful AI agents that need persistent memory across sessions. Honcho is a memory system that reasons about data to build rich peer representations. Use it when you need to maintain context about users, agents, or any entity over time; when you're building chatbots, multi-agent systems, or applications requiring cross-session memory; or when you need to extract insights from conversations through formal logical reasoning.
metadata:
    mintlify-proj: plasticlabs
    version: "1.0"
---

# Honcho Skill

## Product Summary

Honcho is an open-source memory infrastructure for building stateful AI agents. It uses formal logical reasoning to extract insights from messages and build rich representations of peers (users, agents, or any entity). Agents write messages to Honcho, which triggers background reasoning that generates conclusions, summaries, and peer cards. You then query these representations to get synthesized context for your LLM.

**Key files and concepts:**
- **Workspaces** - Top-level containers that isolate applications
- **Peers** - Entities (users, agents) that persist and change over time
- **Sessions** - Interaction threads between peers with temporal boundaries
- **Messages** - Units of data (conversations, events, documents) that trigger reasoning
- **Representations** - Conclusions, summaries, and peer cards generated through reasoning

**SDKs:** Python (`honcho-ai`) and TypeScript (`@honcho-ai/sdk`)

**Primary docs:** https://docs.honcho.dev/v3/documentation/introduction/overview

## When to Use

Reach for Honcho when:
- Building chatbots or conversational agents that need to remember user preferences and history across sessions
- Creating multi-agent systems where agents need to understand each other's perspectives
- Ingesting historical data (emails, documents, transcripts) to build rich user profiles
- You need to extract implicit patterns and insights from conversations (not just retrieve what was said)
- Building personalized experiences that require understanding user behavior over time
- You need to maintain coherent state across long conversations or multiple interactions
- Integrating memory into LLM-powered applications (OpenAI, Anthropic, etc.)

Do NOT use Honcho for:
- Simple key-value storage or caching
- Real-time analytics or metrics collection
- Applications that only need recent message history without reasoning

## Quick Reference

### SDK Installation & Initialization

```python
# Python
from honcho import Honcho

honcho = Honcho(
    workspace_id="my-app",
    api_key="your-api-key",
    environment="production"
)
```

```typescript
// TypeScript
import { Honcho } from "@honcho-ai/sdk";

const honcho = new Honcho({
  workspaceId: "my-app",
  apiKey: process.env.HONCHO_API_KEY,
  environment: "production"
});
```

### Core Operations

| Task | Python | TypeScript |
|------|--------|-----------|
| Create peer | `peer = honcho.peer("user-id")` | `const peer = await honcho.peer("user-id")` |
| Create session | `session = honcho.session("session-id")` | `const session = await honcho.session("session-id")` |
| Add messages | `session.add_messages([peer.message("text")])` | `await session.addMessages([peer.message("text")])` |
| Chat with peer | `peer.chat("What do you know about X?")` | `await peer.chat("What do you know about X?")` |
| Get context | `session.context(tokens=2000)` | `await session.context({ tokens: 2000 })` |
| Convert to OpenAI | `context.to_openai(assistant=assistant)` | `context.toOpenAI(assistant)` |

### Configuration Hierarchy

Settings cascade from workspace → session → message level. Lower levels override higher levels:

```python
# Workspace-level (affects all peers/sessions)
honcho = Honcho(workspace_id="app", api_key="key")

# Session-level (affects peers in this session)
session = honcho.session("id", config={"observe_others": False})

# Message-level (affects this specific message)
session.add_messages([peer.message("text", metadata={"reasoning": False})])
```

### Reasoning Levels for Chat

Use `reasoning_level` to trade speed vs. depth:

| Level | Use Case | Speed | Cost |
|-------|----------|-------|------|
| `minimal` | Fast factual lookups | Fastest | Lowest |
| `low` | Default balance | Fast | Low |
| `medium` | Multi-step questions | Slower | Medium |
| `high` | Complex synthesis | Slow | High |
| `max` | Deep research | Slowest | Highest |

```python
response = peer.chat("Complex question?", reasoning_level="high")
```

## Decision Guidance

### When to Use Chat vs. Context

| Scenario | Use `peer.chat()` | Use `session.context()` |
|----------|-------------------|------------------------|
| Ask Honcho about a peer's preferences | ✓ | |
| Get conversation history for LLM | | ✓ |
| Query what one peer knows about another | ✓ | |
| Format messages for OpenAI/Anthropic | | ✓ |
| Extract insights from reasoning | ✓ | |
| Combine messages + summaries | | ✓ |

### When to Use Summaries vs. Full Messages

| Scenario | Use Summary | Use Full Messages |
|----------|-------------|-------------------|
| Very long conversations (100+ messages) | ✓ | |
| Need recent message detail | | ✓ |
| Token budget is tight | ✓ | |
| Require exhaustive context | | ✓ |
| Combine both (default) | ✓ | ✓ |

### Peer Representation Scope

| Need | Use `peer.context()` | Use `session.context(peer_target=)` |
|------|---------------------|-------------------------------------|
| Global knowledge about peer | ✓ | |
| Session-scoped conclusions only | | ✓ |
| What peer knows about another peer | ✓ | |
| Peer card (biographical facts) | ✓ | ✓ |

## Workflow

### 1. Set Up Workspace and Peers

```python
honcho = Honcho(workspace_id="my-app", api_key=API_KEY, environment="production")
user = honcho.peer("user-123")
assistant = honcho.peer("assistant")
```

### 2. Create Session and Add Peers

```python
session = honcho.session("conversation-1")
session.add_peers([user, assistant])
```

### 3. Ingest Messages (Triggers Reasoning)

```python
session.add_messages([
    user.message("I love Python programming"),
    assistant.message("That's great! What projects do you work on?"),
    user.message("Mostly data science and web backends")
])
```

**Note:** Honcho batches messages (~1,000 tokens) before reasoning. Reasoning happens asynchronously in the background.

### 4. Query Representations

```python
# Ask Honcho what it learned about the user
insights = user.chat("What are this user's main interests?", reasoning_level="medium")

# Get context for your LLM
context = session.context(tokens=2000, peer_target="user-123")
messages = context.to_openai(assistant=assistant)
```

### 5. Integrate with LLM

```python
import openai

# Get formatted context
context = session.context(tokens=3000)
messages = context.to_openai(assistant=assistant)

# Add new user message
messages.append({"role": "user", "content": user_input})

# Get LLM response
response = openai.chat.completions.create(model="gpt-4", messages=messages)

# Add response back to Honcho
session.add_messages([assistant.message(response.choices[0].message.content)])
```

## Common Gotchas

### Reasoning Latency
- Messages are queued for background reasoning, not processed immediately
- Summaries may not be available immediately after adding messages
- Use `session.context(summary=False)` if you need instant context without summaries
- Check queue status with workspace methods if needed

### Token Limits and Context
- Always set `tokens` parameter on `context()` to control size
- Honcho reserves 60% for recent messages, 40% for summary by default
- If token limit is too small, you may get only recent messages (no summary)
- For exhaustive context, don't set a token limit and let Honcho decide

### Peer Representation Scope
- `peer.chat()` queries global representation (all sessions)
- `session.context(peer_target=)` can be scoped to session only with `limit_to_session=True`
- Peer cards are automatically maintained; use `set_card()` to manually override
- Conclusions are stored per peer; use `conclusions_of()` to access what one peer knows about another

### Configuration Cascading
- Message-level config overrides session-level, which overrides workspace-level
- Don't set reasoning=False at workspace level unless you want to disable it everywhere
- Use session-level config for fine-grained control per conversation

### API Key and Environment
- Always use `environment="production"` for production apps
- Store API keys in environment variables, never in code
- New accounts get $100 free credits; monitor usage to avoid overages
- Reasoning is the primary cost driver; adjust reasoning levels to control spend

### Batch Operations
- Batch up to 100 messages in a single `add_messages()` call for efficiency
- Don't create 1,000 peers in a loop; batch peer creation where possible
- Use pagination (`page`, `size`) when listing large numbers of peers/sessions

## Verification Checklist

Before submitting work with Honcho:

- [ ] API key is set in environment variables (not hardcoded)
- [ ] Workspace ID is correct and matches your application
- [ ] Peers are created before adding messages to sessions
- [ ] Messages are added to sessions (not created in isolation)
- [ ] Session has peers added before querying context
- [ ] Token limits are set on `context()` calls to control costs
- [ ] Reasoning level is appropriate for the use case (don't always use `max`)
- [ ] Error handling wraps API calls (network failures, rate limits)
- [ ] Summaries are not expected immediately after adding messages
- [ ] Peer representations are queried with correct scope (global vs. session)
- [ ] LLM context is formatted with correct assistant peer
- [ ] Metadata is used consistently for filtering and tracking

## Resources

**Comprehensive navigation:** https://docs.honcho.dev/llms.txt

**Critical documentation pages:**
1. [Architecture & Core Concepts](https://docs.honcho.dev/v3/documentation/core-concepts/architecture) — Understand workspaces, peers, sessions, messages
2. [SDK Reference](https://docs.honcho.dev/v3/documentation/reference/sdk) — Complete API for Python and TypeScript
3. [Get Context](https://docs.honcho.dev/v3/documentation/features/get-context) — Retrieve and format context for LLMs

---

> For additional documentation and navigation, see: https://docs.honcho.dev/llms.txt