searching-messages

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-agents skill)

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:

1. Find the needle - Search with keywords to discover relevant messages:

   letta messages search --query "flicker inline approval" --limit 5
   

2. Note the message_id - Find the most relevant result and copy its message_id

3. Expand before - Get messages leading up to the needle:

   letta messages list --before "message-xyz" --limit 10
   

4. Expand after - Get messages following the needle (use --order asc for 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 15

Results 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 10

Vector 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 10

Results include agent_id for each message. Use this to:

1. Find the agent that worked on a specific feature
2. Identify the right agent to ask follow-up questions
3. Cross-reference with the finding-agents skill 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 expansion
• message_type - user_message, assistant_message, reasoning_message
• content or reasoning - The actual message text
• created_at - When the message was sent (ISO format)
• agent_id - Which agent the message belongs to