Working Representations

Learn how to retrieve cached peer knowledge and understanding using Honcho’s working representation system

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

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.

Basic Usage

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

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()

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)

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
)

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

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)

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

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)

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:

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

3. Combine with Fresh Analysis When Needed

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

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
}

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.