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
Search query (required)
--mode
Search mode:
vector
,
fts
,
hybrid
(default: hybrid)
--start-date
Filter messages after this date (ISO format)
--end-date
Filter messages before this date (ISO format)
--limit
Max results (default: 10)
--all-agents
Search all agents, not just current agent
--agent
Explicit agent ID (overrides LETTA_AGENT_ID)
--agent-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
Get messages after this ID (cursor)
--before
Get messages before this ID (cursor)
--order
Sort order (default: desc = newest first)
--limit
Max results (default: 20)
--agent
Explicit agent ID (overrides LETTA_AGENT_ID)
--agent-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 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:
Find the agent that worked on a specific feature
Identify the right agent to ask follow-up questions
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