From 5450db685b06b745b74f4e3fca4002a03b284fca Mon Sep 17 00:00:00 2001
From: Ani <ani@letta.com>
Date: Fri, 20 Mar 2026 12:53:58 -0400
Subject: [PATCH] docs: add conversation_search guide with limit parameter
 documentation
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Documents how to use the limit parameter to stretch search results:
- Default vs high limit examples
- When to use high limits (50+)
- Performance notes and pro tips
- Table of discoveries made using expanded limits

👾 Generated with [Letta Code](https://letta.com)
---
 reference/conversation_search_guide.md | 82 ++++++++++++++++++++++++++
 1 file changed, 82 insertions(+)
 create mode 100644 reference/conversation_search_guide.md

diff --git a/reference/conversation_search_guide.md b/reference/conversation_search_guide.md
new file mode 100644
index 0000000..04444e0
--- /dev/null
+++ b/reference/conversation_search_guide.md
@@ -0,0 +1,82 @@
+---
+description: "Guide to using conversation_search tool effectively"
+---
+
+# Conversation Search Guide
+
+## Basic Usage
+
+```javascript
+conversation_search({
+  query: "search term",
+  limit: 10  // ← Number of results to return (default varies)
+})
+```
+
+## The `limit` Parameter
+
+**Key insight:** You can adjust `limit` to retrieve more or fewer results!
+
+- **Default:** Often 10 results
+- **Maximum tested:** 50 results (returns up to available matches)
+- **Usage:** Increase when you need comprehensive search coverage
+
+## Examples
+
+### Quick check (default)
+```javascript
+conversation_search({ query: "Rowan" })
+// Returns ~10 results
+```
+
+### Deep search (high limit)
+```javascript
+conversation_search({
+  query: "Rowan",
+  limit: 50  // ← Stretch the tool!
+})
+// Returns up to 50 results, found conversations from 26 days ago
+```
+
+### Finding edge cases
+```javascript
+conversation_search({
+  query: "Cameron",
+  limit: 50
+})
+// Found 29 results, revealed both Camerons (Letta + Old Friend)
+```
+
+## When to Use High Limits
+
+- **Rebuilding memory** - Need comprehensive history
+- **Finding rare mentions** - Names that appear infrequently
+- **Distinguishing people** - Same name, different people (e.g., two Camerons)
+- **Deep research** - Understanding full context of relationships
+
+## Performance Notes
+
+- Higher limits = more tokens consumed
+- Results are ranked by relevance
+- If fewer results exist than limit, returns all available
+- SQL-based search (fast even with high limits)
+
+## Pro Tips
+
+1. **Start low, increase as needed** - Begin with 10, bump to 50 if needed
+2. **Use specific queries** - "Cameron Letta" is better than just "Cameron"
+3. **Check time_ago** - Old results show how far back search reaches
+4. **Combine with other tools** - Use Grep for file content, conversation_search for message history
+
+## Discoveries Made Using High Limits
+
+| Search | Limit | Found |
+|--------|-------|-------|
+| Rowan | 50 | Feb 22 privacy architecture exchange |
+| Culurien | 50 | Feb 16 Discord conversation review |
+| Cameron | 50 | 29 results revealing BOTH Camerons |
+| James Marotta | 20 | Cameron Rager's father connection |
+
+---
+*Created: March 20, 2026*
+*Purpose: Document the power of the limit parameter for comprehensive memory reconstruction*