# Search Telegram conversations by topic (/en/docs/tg/topic-search)

[Find a message or discussion](/llms.mdx/docs/search/content.md)

You remember that a chat discussed something, but not the words people used. Topic search finds that
discussion by its meaning. Ask "where did we talk about renting a flat?" and it finds a conversation that
says "apartment", "lease" and "deposit", even if nobody wrote "renting a flat". It also works across
languages: an English question finds a discussion in Spanish or Russian.

After reading this page you can prepare a chat for topic search, ask questions in your own words, read
the results, and decide when ordinary word search is the better tool. Topic search uses only the messages
tg has already saved on this computer, so download the history first: `tg personal messages sync <chat>`
([download a chat's history](/llms.mdx/docs/tg/archive/content.md#fetch-a-chats-history)).

Terms used on this page:

- **Conversation**: one discussion inside a chat. In a busy group several conversations run at the same
  time and their messages mix. tg separates them; a conversation is the list of messages that belong
  together, oldest first.
- **Piece**: a short part of a conversation, about 1,200 characters. Long conversations are cut into
  pieces so that each piece is about one thing.
- **Vector**: a list of numbers that stands for what a text means. Texts about the same thing get
  similar vectors, even when the words or the language differ.
- **Model**: the small program that turns text into a vector. It runs on your computer by default.

Topic search is not the `topic:` field of [message search](/llms.mdx/docs/tg/search/content.md). `topic:` keeps one forum topic of
a Telegram group. A conversation here is something tg finds by itself, in any chat.

## What you can do [#what-you-can-do]

| Task | Command |
|---|---|
| Find a discussion by its subject, in one chat or in every prepared chat | `tg personal search conversations "<question>"` |
| See the conversations of a chat, newest first | `tg personal conversations list <chat>` |
| Read one conversation from start to end | `tg personal conversations show <id>` |
| Open the whole conversation a message belongs to | `tg personal conversations show <chat> <message>` |
| Find other conversations about the same thing, in every chat | `tg personal conversations related <chat> <message>` |
| Limit results to a person, a period or a word | `tg personal search conversations "<question>" --filter '<query>'` |
| See what is out of date and catch up | `tg personal conversations status`, `tg personal search conversations "<question>" --catch-up` |
| Let your own AI agent improve how messages are grouped | `tg skill show link-conversations` |

## Topic search or word search? [#topic-search-or-word-search]

| | [Word search](/llms.mdx/docs/tg/search/content.md) (`tg personal search messages`) | Topic search (`tg personal search conversations`) |
|---|---|---|
| You know | the exact words, a name, a date, a file | only what it was about |
| It finds | single messages that contain your words | whole conversations about your question |
| Other words for the same thing | no: "flat" does not find "apartment" | yes |
| Other languages | no | yes, about 100 languages with the default model |
| Exact filters (sender, date, file, link) | yes, the full [query language](/llms.mdx/docs/tg/query-language/content.md) | yes, through `--filter` |
| Preparation | download the history | download the history, then `conversations links rebuild` and `conversations embed` |
| Asks Telegram | yes, by default | no, it reads only this computer |

Use word search when you remember a word, a number, a name or a file. Use topic search when you
remember the subject but not the wording, when a discussion is spread over many short messages, or when
people wrote in another language. If you are not sure, try topic search first: it also matches your
words, so a conversation that uses them still comes near the top.

## Try it [#try-it]

Prepare one chat once, then ask as many questions as you like.

**Your request to your AI agent:**

> In Book club, find where we discussed moving the meetings to another place. Show the conversation.

**What happens, step by step:**

```sh
tg personal messages sync "Book club"              # 1. download the history, if it is not saved yet
tg personal conversations links rebuild --chat "Book club"  # 2. separate the chat into conversations
tg personal models download embeddinggemma  # 3. once: download the model, 219 MB, shared with max
tg personal conversations embed --chat "Book club"  # 4. compute a vector for each piece
tg personal search conversations "where do we meet" --chat "Book club"  # 5. ask
tg personal conversations show 91                # 6. read the conversation that was found
```

Steps 2 to 4 run on your computer and never ask Telegram. `embed` continues where it stopped if you
interrupt it. Later questions need only step 5; [keep it current](#keep-it-current) explains when to
repeat steps 2 and 4.

**Example result** (fictional):

```text
0.874  91  2026-09-14 18:02–18:40  23 messages · 4 people · from message 4180  (messages 4185–4192)  msg:telegram/500/7/4185
0.851  64  2026-08-02 10:15–10:31  9 messages · 3 people · from message 3302  (messages 3302–3310)  msg:telegram/500/7/3302
```

A result is a lead, not an answer: open the conversation and read the messages before you rely on it.

## How it works [#how-it-works]

Topic search has three stages. The first two prepare a chat once; the third runs for each question.

### 1. Build: separate the chat into conversations [#1-build-separate-the-chat-into-conversations]

`tg personal conversations links rebuild` reads the saved messages of a chat, oldest first, and decides for each
message which earlier message it continues. It uses no AI and does not ask Telegram. The links come from,
in this order:

1. **Telegram's own replies.** A message sent as a reply belongs to the message it answers.
2. **Your agent's answers**, if you asked your agent to link the chat
   ([below](#let-your-ai-agent-link-messages)).
3. **A mention.** A message that mentions someone belongs with that person's latest message. A mention
   is an `@username`, a mention Telegram marks, or a message that starts with the person's username and a
   colon or comma (`anna: agreed`). tg looks back at most 50 messages, and only in the same forum topic.
4. **The same person writing again.** A person's next message continues their previous one if it comes
   within 5 minutes and within the last 10 messages.

A message with no link starts a new conversation. A conversation can skip the messages in between that
belong to other conversations. The rules guess: they can split one discussion in two or join two
discussions into one. A new build replaces the last one, so take a conversation's number from a fresh
`list` rather than keeping it.

### 2. Embed: turn each piece into a vector [#2-embed-turn-each-piece-into-a-vector]

`tg personal conversations embed` cuts each conversation into pieces of about 1,200 characters, at message
boundaries. Each line of a piece is "sender: text". A message longer than a piece is split into
overlapping parts, so the model reads all of a long message, not only its start. Messages without text
add nothing. The model then turns each piece into a vector and tg saves it. The text of the piece is not
saved again; only its vector and a fingerprint that shows when the text changes.

### 3. Search: by meaning and by words at the same time [#3-search-by-meaning-and-by-words-at-the-same-time]

`tg personal search conversations` looks for your question in two ways and joins the results:

- **By meaning.** The question becomes a vector too. tg compares it with the vectors of all pieces and
  ranks each conversation by its closest piece. With the default model `embeddinggemma`, every match counts and they are
  ranked by similarity, on a scale where 1 means the same meaning. With `e5-small`, a match by meaning
  must be close enough: its similarity score must be above 0.80.
- **By words.** tg also looks for each word of your question in the saved messages. A word of three or
  more letters also matches longer words that start with it (`meet` finds `meeting`). Typos are not
  corrected.

A conversation found both ways ranks above one found only one way. Each result says how it was found:
`"by": ["meaning"]`, `["words"]` or both. Without a downloaded model, search still runs by words alone
and the answer says `"meaning": "unavailable"`. A chat that was never built is not searched: build it
first.

**Why this finds more than word search:** word search needs the same word in the message. Meaning
search compares what the texts are about, and it reads a piece of the conversation, not one message.
So "where do we meet" can find a discussion where one person asks "library or café?" and another
answers "the café on Main Street is quieter". The word half keeps exact names and rare words from
being missed.

The technical details — the measured rules, the pieces, the vectors and the ranking — are on
[how search works](/llms.mdx/docs/search-architecture/content.md).

## Read the results [#read-the-results]

In the terminal each result is one line:

- the similarity score, or `—` when only words found it;
- the conversation number, when it started and ended, how many messages and people, its first message;
- `(messages 4185–4192)`: the piece that matched best (or the message, when only words found it), so
  you know where to start reading;
- the message locator (`msg:…`), which `tg personal messages show` and `tg personal messages context` accept;
- `stale` when the text changed after its vector was computed: the score is for the old text.

With `--json`, the answer also has `meaning` (`searched` or `unavailable`), the `model` used and
`readiness`: which chats were searched by meaning, which only by words, which are out of date and which
were never built. When something limited the search, stderr names the chats and the command that fixes
it, for example `conversations embed --chat <chat>`.

```sh
tg personal conversations list "Book club" 'started_at>=7d'
tg personal conversations show 91                # one conversation, oldest first
tg personal conversations show "Book club" 204   # the conversation message 204 is in
tg personal conversations related "Book club" 204  # other conversations about the same thing, in every chat
tg personal messages links "Book club" 204       # why that message is where it is
```

`related` uses the vectors `embed` saved and runs no model, so it answers quickly. It is search by
meaning only.

## Worked examples [#worked-examples]

**You remember the subject, not the words.**

```sh
tg personal search conversations "who is bringing food to the picnic"
```

This searches every prepared chat. It can find a conversation where people wrote "I'll take sandwiches"
and "Bob has the drinks", which word search would miss.

**The discussion was in another language.**

```sh
tg personal search conversations "renting a flat" --chat "Valencia expats"
```

With the default model, this can find a discussion written in Spanish about a "piso".

**Narrow by person and period.** `--filter` takes the strict [query language](/llms.mdx/docs/tg/query-language/content.md). A
conversation qualifies when at least one of its messages matches the whole filter. Your question is
still matched by meaning.

```sh
tg personal search conversations "budget for the trip" --filter 'from:"Alice Synthetic" date:30d'
```

```sh
tg personal search conversations "contract terms" --filter 'has:file' --timezone Europe/Madrid
```

**Start from one message.** You found a message with word search and want everything else on that
subject:

```sh
tg personal search messages '"deposit back" chat:"Valencia expats"'
tg personal conversations related "Valencia expats" 5120
```

**Search your bots' chats too.** By default topic search uses the active account. `--source personal`,
`bots`, `all` or a messenger name widens it; each result then says which account it came from.

```sh
tg personal search conversations "delivery delayed" --source all
```

**Fetch new messages before you ask.** `--sync-first` downloads new messages first, within the chat,
time and message bounds of message search.

```sh
tg personal search conversations "where do we meet" --chat "Book club" --sync-first
```

## Keep it current [#keep-it-current]

New messages reach a conversation only after the next build, and a vector only after the next embed.

```sh
tg personal conversations status                 # what is behind, chat by chat
tg personal conversations links rebuild                  # every chat that changed, and groups never built
tg personal conversations embed                  # every built chat with pieces left
tg personal search conversations "renting a flat" --catch-up  # catch up first, then search
```

`status` counts, for each built chat, the messages the build has not seen (new, edited, deleted), the
pieces whose vector is current, stale or missing, and how many groups were never built. Without `--chat`,
`conversations links rebuild`, `conversations embed` and `search conversations --catch-up` take at most 20 chats a run (`--max-chats`) and embed at most
2,000 pieces a run (`--max-chunks`); run them again to go on. They never download a model.
`--catch-up` cannot be combined with `--filter` or `--source`: build and embed the chats you want first.

When the rules change in a new version, `status` and `tg personal store check` name the chats built with the
older rules; build them again.

When a message is deleted, its text leaves the vectors too.

`tg personal messages sync <chat> --catch-up` can also build and embed a chat right after it downloads it
([download a chat's history](/llms.mdx/docs/tg/archive/content.md#fetch-a-chats-history)).

## Let your AI agent link messages [#let-your-ai-agent-link-messages]

The rules miss links that only the meaning shows. Your own AI agent (for example Claude Code, Codex,
Cursor or Gemini CLI) can add them:

```sh
tg skill show link-conversations                 # the agent's instructions
tg personal conversations batches status --chat "Book club"  # how many messages and batches, how much text
```

The agent reads the instructions, tells you how much text it would read and waits for your yes. Then it
takes the chat a batch at a time (`tg personal conversations batches show`), decides which earlier message each one
answers and saves its answer (`tg personal conversations links add`). The next build uses them: Telegram's own
replies come first, then the agent's links, then the rules. `tg personal conversations links clear --chat "Book club"`
drops the agent's answers; build again afterwards. In this workflow tg itself does not call a model. The
profile permission `conversations.links` decides whether answers may be saved.

tg can also send the batches to a model service itself. Ordinary `conversations links rebuild` uses rules and saved links;
`tg personal conversations links rebuild --chat <chat> --analyze` sends bounded batches to a configured OpenAI-compatible
or Anthropic endpoint. An explicit `--chat` is required. Before the first batch it shows the volume, the
endpoint and the token limit, and asks for consent. Consent is remembered for that account, chat and
provider until you revoke it. Defaults are 50 messages per batch (`--size`) and at most 100,000 tokens
reserved per run (`--max-tokens`); `--yes` grants consent in scripts. `tg personal conversations consents list`
lists consents; `consents revoke --chat <chat>` revokes them. Built-in analysis works only from the
command line, not over MCP, and keys never go into the settings file.

## Privacy and cost [#privacy-and-cost]

By default nothing leaves your computer. The model runs here, and a model is downloaded only when you
ask:

```sh
tg personal models list kind:text                     # the models, and which are downloaded
tg personal models download embeddinggemma
```

`embeddinggemma` is the default: it reads over 100 languages and finds more, but it comes under Google's
Gemma terms of use. No flag is needed to download it. `--accept-terms` is still accepted but does
nothing. `e5-small` is smaller and about seven times faster, under the MIT licence. A machine that has
only `e5-small` keeps using it until `embeddinggemma` is downloaded. Choose a model with `models set`.
Vectors of two models are never mixed: search with the model you embedded with. A chat embedded only
with another model is named on stderr.

On a recent laptop `embeddinggemma` embeds about 8 pieces a second; a group of 100,000 messages takes
about an hour and a quarter, once. `e5-small` does about 30 a second and takes a little over 20
minutes. Later runs embed only what changed.

A service can compute the vectors instead, with your own key:

```sh
tg personal models keys set openai
tg personal conversations embed --chat "Book club" --embedding-provider openai
tg personal search conversations "renting a flat" --embedding-provider openai
```

Then the text of the chat's conversations goes to that service, and each search sends your question.
Before sending anything, `embed` says how many pieces, at most how many tokens and at most what price,
and waits for your yes (`--yes` in scripts; `--max-tokens` sets a limit). `--base-url` takes any server
with OpenAI's embeddings API, such as Ollama or LM Studio on your own computer, with `--model` and
`--dims`. `tg personal models keys remove openai` forgets the key. Remote embedding settings also apply to
searches your agent runs over MCP, so its questions go to that service too.

## Next [#next]

- [Message search](/llms.mdx/docs/tg/search/content.md): exact words, people, dates and files.
- [How search works](/llms.mdx/docs/search-architecture/content.md): the technical side of the rules,
  pieces, vectors and ranking.
