Skip to main content
Honcho’s search functionality allows you to find relevant messages and conversations across different scopes - from entire workspaces down to specific peers or sessions.
Search is hybrid: it combines full-text (keyword) matching with semantic (vector) similarity. Keyword matches are available the instant a message is created. Semantic matches depend on the message’s embedding, which is generated in the background, so a freshly created message may take a few seconds to surface in semantic results. If you need to assert on semantic results immediately after writing (for example in tests), wait briefly or poll.

​
Search Scopes

Search across all content in your workspace - sessions, peers, and messages: 
from honcho import Honcho

# Initialize client
honcho = Honcho()

# Search across entire workspace
results = honcho.search("budget planning")

# Iterate through all results
for result in results:
    print(f"Found: {result}")
Search within a specific session’s conversation history: 
# Create or get a session
session = honcho.session("team-meeting-jan")

# Search within this session only
results = session.search("action items")

# Process results
for result in results:
    print(f"Session result: {result}")
Search across all content associated with a specific peer: 
# Create or get a peer
alice = honcho.peer("alice")

# Search across all of Alice's messages and interactions
results = alice.search("programming")

# View results
for result in results:
    print(f"Alice's content: {result}")

​
Filters and Limits

​
Get a specific number of results

You can specify the number of results you want to return by passing the limit parameter to the search method. The default is 10 results, with a maximum of 100. 
results = honcho.search("budget planning", limit=20)

​
Get messages from a Peer in a specific Session

Combine Peer-level search with a session_id filter to get messages from a Peer in a specific Session. 
my_peer = honcho.peer("my-peer")
my_session = honcho.session("team-meeting-jan")
results = my_peer.search("budget planning", filters={"session_id": my_session.id})
Search returns an object containing an items array of message objects: 
{
  "items": [
    {
      "id": "<string>",
      "content": "<string>",
      "peer_id": "<string>",
      "session_id": "<string>",
      "metadata": {},
      "created_at": "2023-11-07T05:31:56Z",
      "workspace_id": "<string>",
      "token_count": 123
    }
  ]
}

​
Filter results by time range

results = honcho.search("budget planning", filters={"created_at": {"gte": "2024-01-01", "lte": "2024-01-31"}})

​
Filter results by metadata

results = honcho.search("budget planning", filters={"metadata": {"key": "value"}})

​
Best Practices

​
Handle Empty Results Gracefully

# Always check for empty results
results = honcho.search("very specific query")
result_list = list(results)

if result_list:
    print(f"Found {len(result_list)} results")
    for result in result_list:
        print(f"- {result}")
else:
    print("No results found - try a broader search")

​
Conclusion

Honcho’s search functionality provides powerful discovery capabilities across your conversational data. By understanding how to:
  • Choose the appropriate search scope (workspace, session, or peer)
  • Handle paginated results effectively
  • Combine search with context building
You can build applications that provide intelligent insights and context-aware responses based on historical conversations and interactions.