Searching Messages
This skill helps you search through past conversations to recall context that may have fallen out of your context window.
When to Use This Skill
- User asks "do you remember when we discussed X?"
- You need context from an earlier conversation
- User references something from the past that you don't have in context
- You want to verify what was said before about a topic
- You need to find which agent discussed a specific topic (use with
finding-agentsskill)
CLI Usage
letta messages search --query <text> [options]Options
| Option | Description |
|---|---|
--query <text> | Search query (required) |
--mode <mode> | Search mode: vector, fts, hybrid (default: hybrid) |
--start-date <date> | Filter messages after this date (ISO format) |
--end-date <date> | Filter messages before this date (ISO format) |
--limit <n> | Max results (default: 10) |
--all-agents | Search all agents, not just current agent |
--agent <id> | Explicit agent ID (overrides LETTA_AGENT_ID) |
--agent-id <id> | Alias for --agent |
Search Modes
- hybrid (default): Combines vector similarity + full-text search with RRF scoring
- vector: Semantic similarity search (good for conceptual matches)
- fts: Full-text search (good for exact phrases)
Companion Command: messages list
Use this to expand around a found needle by message ID cursor:
letta messages list [options]| Option | Description | |
|---|---|---|
--after <message-id> | Get messages after this ID (cursor) | |
--before <message-id> | Get messages before this ID (cursor) | |
| `--order <asc\ | desc>` | Sort order (default: desc = newest first) |
--limit <n> | Max results (default: 20) | |
--agent <id> | Explicit agent ID (overrides LETTA_AGENT_ID) | |
--agent-id <id> | Alias for --agent |
Search Strategies
Strategy 1: Needle + Expand (Recommended)
Use when you need full conversation context around a specific topic:
- Find the needle - Search with keywords to discover relevant messages:
letta messages search --query "flicker inline approval" --limit 5 - Note the message_id - Find the most relevant result and copy its
message_id - Expand before - Get messages leading up to the needle:
letta messages list --before "message-xyz" --limit 10 - Expand after - Get messages following the needle (use
--order ascfor chronological):letta messages list --after "message-xyz" --order asc --limit 10
Strategy 2: Date-Bounded Search
Use when you know approximately when something was discussed:
letta messages search --query "topic" --start-date "2025-12-31T00:00:00Z" --end-date "2025-12-31T23:59:59Z" --limit 15Results are sorted by relevance within the date window.
Strategy 3: Broad Discovery
Use when you're not sure what you're looking for:
letta messages search --query "vague topic" --mode vector --limit 10Vector mode finds semantically similar messages even without exact keyword matches.
Strategy 4: Find Which Agent Discussed Something
Use with --all-agents to search across all agents and identify which one discussed a topic:
letta messages search --query "authentication refactor" --all-agents --limit 10Results include agent_id for each message. Use this to:
- Find the agent that worked on a specific feature
- Identify the right agent to ask follow-up questions
- Cross-reference with the
finding-agentsskill to get agent details
Tip: Load both searching-messages and finding-agents skills together when you need to find and identify agents by topic.
Search Output
Returns search results with:
message_id- Use this for cursor-based expansionmessage_type-user_message,assistant_message,reasoning_messagecontentorreasoning- The actual message textcreated_at- When the message was sent (ISO format)agent_id- Which agent the message belongs to