> ## Documentation Index
> Fetch the complete documentation index at: https://honcho.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Search

> Learn how to search across workspaces, sessions, and peers to find relevant conversations and 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.

<Note>
  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.
</Note>

## Search Scopes

### Workspace Search

Search across all content in your workspace - sessions, peers, and messages:

<CodeGroup>
  ```python Python theme={null}
  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}")
  ```

  ```typescript TypeScript theme={null}
  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}`);
      }
  })();
  ```
</CodeGroup>

### Session Search

Search within a specific session's conversation history:

<CodeGroup>
  ```python Python theme={null}
  # 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}")
  ```

  ```typescript TypeScript theme={null}
  (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}`);
      }
  })();
  ```
</CodeGroup>

### Peer Search

Search across all content associated with a specific peer:

<CodeGroup>
  ```python Python theme={null}
  # 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}")
  ```

  ```typescript TypeScript theme={null}
  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}`);
      }
  })();
  ```
</CodeGroup>

## 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.

<CodeGroup>
  ```python Python theme={null}
  results = honcho.search("budget planning", limit=20)
  ```

  ```typescript TypeScript theme={null}
  (async () => {
      const results = await honcho.search("budget planning", { limit: 20 });
  })();
  ```
</CodeGroup>

### 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.

<CodeGroup>
  ```python Python theme={null}
  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})
  ```

  ```typescript TypeScript theme={null}
  (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 } });
  })();
  ```
</CodeGroup>

Search returns an object containing an `items` array of message objects:

```json theme={null}
{
  "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

<CodeGroup>
  ```python Python theme={null}
  results = honcho.search("budget planning", filters={"created_at": {"gte": "2024-01-01", "lte": "2024-01-31"}})
  ```

  ```typescript TypeScript theme={null}
  (async () => {
      const results = await honcho.search("budget planning", { filters: { created_at: { gte: "2024-01-01", lte: "2024-01-31" } } });
  })();
  ```
</CodeGroup>

### Filter results by metadata

<CodeGroup>
  ```python Python theme={null}
  results = honcho.search("budget planning", filters={"metadata": {"key": "value"}})
  ```

  ```typescript TypeScript theme={null}
  (async () => {
      const results = await honcho.search("budget planning", { filters: { metadata: { key: "value" } } });
  })();
  ```
</CodeGroup>

### Best Practices

### Handle Empty Results Gracefully

<CodeGroup>
  ```python Python theme={null}
  # 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")
  ```

  ```typescript TypeScript theme={null}
  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");
      }
  })();
  ```
</CodeGroup>

## 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.