Search

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

Workspace Search

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}")

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

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

    // Search across entire workspace
    const results = await honcho.search("budget planning");

    // Iterate through all results
    for (const result of results) {
      console.log(`Found: ${result}`);
    }
})();

Session Search

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}")

(async () => {
    // Create or get a session
    const session = await honcho.session("team-meeting-jan");

    // Search within this session only
    const results = await session.search("action items");

    // Process results
    for (const result of results) {
      console.log(`Session result: ${result}`);
    }
})();

Peer Search

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}")

import { Message } from "@honcho-ai/sdk";

(async () => {
    // Create or get a peer
    const alice = await honcho.peer("alice");

    // Search across all of Alice's messages and interactions
    const results: Message[] = await alice.search("programming");

    // View results
    for (const result of results) {
      console.log(`Alice's content: ${result.content}`);
    }
})();

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)

(async () => {
    const results = await 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})

(async () => {
    const myPeer = await honcho.peer("my-peer");
    const mySession = await honcho.session("team-meeting-jan");
    const results = await myPeer.search("budget planning", { filters: { session_id: mySession.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"}})

(async () => {
    const results = await 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"}})

(async () => {
    const results = await 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")

import { Message } from "@honcho-ai/sdk";

(async () => {
    // Always check for empty results
    const results: Message[] = await honcho.search("very specific query");

    if (results.length > 0) {
      console.log(`Found ${results.length} results`);
      for (const result of results) {
        console.log(`- ${result.content}`);
      }
    } else {
      console.log("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.

Introduction

Core Concepts

Features

Reference

Search Scopes

Workspace Search

Session Search

Peer Search

Filters and Limits

Get a specific number of results

Get messages from a Peer in a specific Session

Filter results by time range

Filter results by metadata

Best Practices

Handle Empty Results Gracefully

Conclusion

​Search Scopes

​Workspace Search

​Session Search

​Peer Search

​Filters and Limits

​Get a specific number of results

​Get messages from a Peer in a specific Session

​Filter results by time range

​Filter results by metadata

​Best Practices

​Handle Empty Results Gracefully

​Conclusion

Search Scopes

Workspace Search

Session Search

Peer Search

Filters and Limits

Get a specific number of results

Get messages from a Peer in a specific Session

Filter results by time range

Filter results by metadata

Best Practices

Handle Empty Results Gracefully

Conclusion