honcho/docs/v2.6.0-alpha/documentation/scratch/working-rep.mdx

---
title: 'Working Representations'
description: "Learn how to retrieve cached peer knowledge and understanding using Honcho's working representation system"
icon: 'brain'
---

Working representations are Honcho's system for accessing cached psychological models that capture what peers know, think, and remember. Unlike the `chat()` method which generates fresh representations on-demand, the `working_rep()` method retrieves pre-computed representations that have been automatically built and stored as conversations progress.

## How Working Representations Are Created

Working representations are automatically generated and cached through Honcho's background processing system:

1. **Automatic Generation**: When messages are added to sessions, they trigger background jobs that analyze conversations using theory of mind inference and long-term memory integration

2. **Cached Storage**: The generated representations are stored in the database as metadata on `Peer` objects (for global representations) or `SessionPeer` objects (for session-scoped representations)

3. **Retrieval**: The `working_rep()` method provides fast access to these cached representations without requiring LLM processing

<Info>
**Cached vs On-Demand**: `working_rep()` retrieves cached representations for fast access, while `peer.chat()` generates fresh representations using the dialectic system. Use `working_rep()` when you need fast access to stored knowledge, and `chat()` when you need current analysis with custom queries.
</Info>

## Basic Usage

Working representations are accessed through the `working_rep()` method on Session or Peer objects:

<CodeGroup>
```python Python
from honcho import Honcho

# Initialize client
honcho = Honcho()

# Create peers and session
user = honcho.peer("user-123")
assistant = honcho.peer("ai-assistant")
session = honcho.session("support-conversation")

# Add conversation to trigger representation generation
session.add_messages([
    user.message("I'm having trouble with my billing account"),
    assistant.message("I can help with that. What specific issue are you seeing?"),
    user.message("My credit card was charged twice last month"),
    assistant.message("I see duplicate charges on your account. Let me refund one of them.")
])

# Chat to generate a working representation
response = user.chat("What is this user's main concern right now?", session_id=session.id)

# Retrieve the cached working representation for the user
user_representation = session.working_rep("user-123")
print("Cached user representation:", user_representation)

# Or access from the peer directly
peer_representation = user.working_rep()
```

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

// Initialize client
const honcho = new Honcho({});

// Create peers and session
const user = await honcho.peer("user-123");
const assistant = await honcho.peer("ai-assistant");
const session = await honcho.session("support-conversation");

// Add conversation to trigger representation generation
await session.addMessages([
  user.message("I'm having trouble with my billing account"),
  assistant.message("I can help with that. What specific issue are you seeing?"),
  user.message("My credit card was charged twice last month"),
  assistant.message("I see duplicate charges on your account. Let me refund one of them.")
]);

// Chat to generate a working representation
const response = await user.chat("What is this user's main concern right now?", { sessionId: session.id });

// Retrieve the cached working representation for the user
const userRepresentation = await session.workingRep("user-123");
console.log("Cached user representation:", userRepresentation);

// Or access from the peer directly
const peerRepresentation = await user.workingRep();
```
</CodeGroup>

## Semantic Search in Representations

Working representations support semantic search to retrieve the most relevant observations for a given query. This is useful when you want to focus the representation on specific topics.

### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `search_query` | `str` | Semantic search query to filter relevant observations |
| `search_top_k` | `int` | Number of semantic search results to include (1-100) |
| `search_max_distance` | `float` | Maximum semantic distance threshold (0.0-1.0) |
| `include_most_derived` | `bool` | Whether to include the most recently derived observations |
| `max_observations` | `int` | Maximum number of observations to include (1-100) |

<CodeGroup>
```python Python
# Get representation focused on a specific topic
billing_rep = session.working_rep(
    "user-123",
    search_query="billing and payment issues",
    search_top_k=10,
    search_max_distance=0.8,
    include_most_derived=True,
    max_observations=25
)

# Get representation from peer with target
# What user-123 knows about the assistant
local_rep = session.working_rep(
    "user-123",
    target="ai-assistant",
    search_query="support interactions"
)

# Access from peer object with semantic search
user_rep = user.working_rep(
    session=session,
    search_query="preferences",
    search_top_k=5
)
```

```typescript TypeScript
// Get representation focused on a specific topic
const billingRep = await session.workingRep("user-123", {
  searchQuery: "billing and payment issues",
  searchTopK: 10,
  searchMaxDistance: 0.8,
  includeMostDerived: true,
  maxObservations: 25
});

// Get representation from peer with target
// What user-123 knows about the assistant
const localRep = await session.workingRep("user-123", {
  target: "ai-assistant",
  searchQuery: "support interactions"
});

// Access from peer object with semantic search
const userRep = await user.workingRep(session, undefined, {
  searchQuery: "preferences",
  searchTopK: 5
});
```
</CodeGroup>

## Understanding Representation Content

Cached working representations contain structured psychological analysis based on conversation history. The format typically includes:

### Current Mental State Predictions
Information about what the peer is currently thinking, feeling, or focused on based on recent messages.

### Relevant Long-term Facts
Facts about the peer that have been extracted and stored over time from various conversations.

### Example Representation Structure

<CodeGroup>
```python Python
# Example of what a cached representation might contain
representation = session.working_rep("user-123")

# Typical content structure:
"""
PREDICTION ABOUT THE USER'S CURRENT MENTAL STATE:
The user appears frustrated with a billing issue, specifically concerning duplicate charges.
They seem to have some confidence in the support process as they provided specific details.

RELEVANT LONG-TERM FACTS ABOUT THE USER:
- User has had previous billing inquiries
- User prefers direct, specific communication
- User is detail-oriented when reporting issues
"""

print("Full representation:", representation)
```

```typescript TypeScript
// Example of what a cached representation might contain
const representation = await session.workingRep("user-123");

// Typical content structure:
/*
PREDICTION ABOUT THE USER'S CURRENT MENTAL STATE:
The user appears frustrated with a billing issue, specifically concerning duplicate charges.
They seem to have some confidence in the support process as they provided specific details.

RELEVANT LONG-TERM FACTS ABOUT THE USER:
- User has had previous billing inquiries
- User prefers direct, specific communication
- User is detail-oriented when reporting issues
*/

console.log("Full representation:", representation);
```
</CodeGroup>

## When Representations Are Updated

Working representations are automatically updated through Honcho's background processing system:

### Message Processing Pipeline

1. **Message Creation**: When messages are added via `session.add_messages()` or similar methods
2. **Background Queuing**: Messages are queued for processing in the background
3. **Theory of Mind Analysis**: The system analyzes conversation patterns and psychological states
4. **Fact Extraction**: Long-term facts are extracted and stored in vector embeddings
5. **Representation Generation**: New representations are created combining current analysis with historical facts
6. **Cache Update**: The new representation is stored in the database metadata

### Processing Triggers

Representations are updated when:
- New messages are added to sessions
- Sufficient new content has accumulated
- The background processing system determines an update is needed

## Comparison with Chat Method

Understanding when to use `working_rep()` vs `peer.chat()`:

### Use `working_rep()` when:
- You need fast access to stored psychological models
- You want to see what the system has already learned about a peer
- You're building dashboards or analytics that display peer understanding
- You need consistent representations that don't change between calls

### Use `peer.chat()` when:
- You need to ask specific questions about a peer
- You want fresh analysis based on current conversation state
- You need customized insights for specific use cases
- You want to query about relationships between peers

<CodeGroup>
```python Python
# Fast cached access
cached_rep = session.working_rep("user-123")
print("Cached:", cached_rep[:100] + "...")

# Custom query with fresh analysis
custom_analysis = user.chat("What is this user's main concern right now?", session_id=session.id)
print("Fresh analysis:", custom_analysis)
```

```typescript TypeScript
// Fast cached access
const cachedRep = await session.workingRep("user-123");
console.log("Cached:", cachedRep.substring(0, 100) + "...");

// Custom query with fresh analysis
const customAnalysis = await user.chat("What is this user's main concern right now?", { sessionId: session.id });
console.log("Fresh analysis:", customAnalysis);
```
</CodeGroup>

## Best Practices

### 1. Ensure Availability Before Using

Make sure that a representation exists before processing it by using the chat endpoint first.

### 2. Use for Fast Analytics

Cached representations are ideal for analytics dashboards:

<CodeGroup>
```python Python
# Good: Fast dashboard updates using cached data
def update_analytics_dashboard(sessions):
    analytics = {}
    for session in sessions:
        for peer_id in session.get_peer_ids():
            rep = session.working_rep(peer_id)
            analytics[peer_id] = analyze_representation(rep)
    return analytics
```

```typescript TypeScript
// Good: Fast dashboard updates using cached data
async function updateAnalyticsDashboard(sessions) {
  const analytics: Record<string, any> = {};
  for (const session of sessions) {
    const peerIds = await session.getPeerIds();
    for (const peerId of peerIds) {
      const rep = await session.workingRep(peerId);
      analytics[peerId] = analyzeRepresentation(rep);
    }
  }
  return analytics;
}
```
</CodeGroup>

### 3. Combine with Fresh Analysis When Needed

Use cached representations for baseline understanding, and fresh analysis for current insights:

<CodeGroup>
```python Python
# Get baseline understanding from cache
baseline = session.working_rep("user-123")

# Get current specific insights
current_state = user.chat("How is this user feeling right now?", session_id=session.id)

# Combine for comprehensive view
comprehensive_view = {
    "baseline_knowledge": baseline,
    "current_analysis": current_state
}
```

```typescript TypeScript
// Get baseline understanding from cache
const baseline = await session.workingRep("user-123");

// Get current specific insights
const currentState = await user.chat("How is this user feeling right now?", { sessionId: session.id });

// Combine for comprehensive view
const comprehensiveView = {
  baselineKnowledge: baseline,
  currentAnalysis: currentState
};
```
</CodeGroup>

## Conclusion

Working representations provide fast access to cached psychological models that Honcho automatically builds and maintains. By understanding how to:

- Retrieve cached representations using `session.working_rep()`
- Parse and interpret representation content
- Handle cases where representations aren't available
- Combine cached and fresh analysis appropriately

You can build efficient applications that leverage Honcho's continuous learning about peer knowledge and mental states without the latency of real-time generation.