How things are linked
Which records the tools connect (messages, people, chats, files, mentions, notes, tasks, facts, Drive documents, tags), who creates each link, and what to run when one is missing.
You can ask your agent for everything about one person, or for the messages behind a decision, because the tools keep links between records. This page explains which links exist, who creates each one (the tool, you or your agent) and how to follow them. After it, you can tell why a link is missing and which command adds it. Search and links work on what is already in the local store, so download the history first: Searching.
The idea
tg, max, memo and drive keep their records in one local store on your computer. A record from one tool can link to a record from another. A link is one of two things:
- Part of the record. A message has a chat and a sender.
- A stored link between two records. A note is about a person. A fact is backed by messages.
Identities are never joined by guessing from names. Each stored link records who made it.
A reference names any record
Every result carries a reference: a short typed name for the record. Copy it into the next command.
| Reference | What it points to |
|---|---|
msg:telegram/1/77/42 | One message: messenger, account, chat, message |
chat:telegram/1/77 | A chat in one account |
contact:telegram/501 | A contact in one messenger |
person:7 | A person, with all the accounts you linked to them |
organization:3, project:4, task:5 | Your organizations, projects and tasks |
note:12, document:3 | A note, or a file from a notes folder or Drive |
memory:8, fact:9 | A memory or a fact |
A message reference includes the account, so the same message number in another account is a different message. The field that holds the reference is ref in most answers. A few answers call it locator, and one Drive list calls it reference. Copy the value, not the field name.
tg personal messages context "msg:telegram/1/77/42" --threadMessages, chats and people
A message belongs to one chat and has a sender. The sender is an identity: one account in one messenger. A person is one or more identities.
Only you join identities into one person. The same name or the same email domain is never enough.
tg personal contacts link "Kai Sample" max:KaiAfter that, contacts timeline follows the person across messengers. It lists what they wrote, where they were mentioned, and their chats, mail, meetings and tasks, newest first, from the store only.
tg personal contacts timeline "Kai Sample" --since-time 2026-10-01 --limit 20The tool also records who took part in what (sender, recipient, participant, assignee, author, mentioned, linked). That record is why "everything about Kai" is one lookup and not a scan of every message.
Replies and conversations
Every message can point at the earlier message it answers. Each pointer says where it came from:
- The messenger. An explicit reply. It wins over everything else.
- A rule of the tool. A message that mentions someone, or that continues the same sender.
- Your agent. An answer it stored after reading the chat. Storing it needs the profile permission
conversations.links.
conversations build joins these pointers into conversations for one chat. messages context with --thread follows the chain from a message instead of showing its neighbours in time. A link that went out of date after an edit or a deletion is shown but never followed. A rebuild gives conversations new ids, so keep the msg: reference of the message, not the conversation id. How the graph is built: How search works.
Files, voice notes and pictures
- A file belongs to a message, an email or a meeting. Its extracted text stays with it, so
content:finds the message that carried the file. - A voice note's transcript belongs to the message, so
transcript:finds that message. - A picture is found through the chat around it or through what it shows. Both are explained in What gets indexed.
Mentions
A mention is a phone number, an email address, a link, a Google document link, or the name of a person you know, found by rules in message text, file text and transcripts. Each mention starts as found. You then confirm it (linked) or reject it (dismissed).
mentions listshows what was found.mentions show <id>shows the text around one.mentions confirm <id> person:7says who owns a phone number or an address, or which person a name means.person:ororganization:both work for a phone or an address. A stored Google document needs no argument.mentions reject <id>dismisses that value everywhere and on later syncs. A plain link cannot be confirmed, only rejected.mentions rebuildreads messages stored before mentions existed.mentions rebuild person-namefinds names again after you add or rename people.
Both record who decided. When an agent runs them, the decision is stored under the agent's name; --as-owner stores it as yours.
Search finds mentions however they were written: phone:, email:, url: and domain: look at the value, and mentions:"person:7" finds messages that mention a confirmed person, organization or document. These commands are in the latest releases of tg and max; run mentions --help to check yours. More: What gets indexed.
Notes, tasks, facts and memories
memo keeps the records that you or your agent write about everything above.
- A note is about a person, a chat, a task or a document. A
[[Kai Sample]]link in a note becomes a link to that person once someone with that name or username is in the store. A name in plain text is not a link. - A task can come from a message. A question task links to the message that answered it.
- A fact (a statement, a question, a decision or a promise) keeps links to its evidence: the messages, notes or documents behind it. A new decision can replace an earlier one. A fact your agent adds waits as proposed until you accept it.
- A memory is a conclusion with evidence and a review status. A change in the source can make it stale.
Tags
A tag goes on any record: a message, a chat, a person, a document, a note, a task. tag:work finds a message that has the tag, a message in a chat that has it, and a message from a person that has it. A tag on a Drive folder reaches every document inside it.
tg personal tags add work --chat "Book club"Drive documents
drive imports documents into the same store. A document can carry tags, notes, facts and memories, and link to a person (drive relationships, drive tags). drive documents list --person person:7 lists the documents linked to that person.
Who makes a link
| Link | Made by |
|---|---|
| A message in its chat, with its sender | The tool, when it saves the message |
| A reply | The messenger |
| A guessed reply (mention, same sender) | A rule of the tool |
| A chosen reply | Your agent, with conversations.links |
| A phone, email, link, document or name found in text | A rule of the tool, as found |
| A mention confirmed or rejected | You, or your agent, recorded by name |
| Two identities, one person | You, with contacts link |
| A tag | You, with tags add |
| A note, a task or a fact about a record | You, or your agent through memo |
| A fact from an agent | Your agent, as proposed; you accept it |
Each stored link records its source: file (written in a note file), owner (added by you), suggested (proposed, not yet confirmed) or message (written in a stored message).
Use links in a question
Four requests an agent can answer because of links. Replace the names with yours.
Use tg CLI. Find the message where we agreed on the delivery date, then show the messages around it as one conversation.Use tg CLI. Who owns the phone number +1 555 010 0100? Show where it appears and propose a person.Use tg CLI. Show everything about Kai Sample in the last month, across every messenger I linked to them.Use memo. Which task came from the message about the invoice, and which message answered it?If a link is missing
| Symptom | Likely cause | What to do |
|---|---|---|
| A person's timeline shows one messenger only | The identities are not linked | contacts link, then ask again |
--thread shows only neighbours in time | No conversations built for the chat | conversations build --chat "Book club" |
| A phone or email in an old message is not found | The message was stored before mentions existed | mentions rebuild |
| A name of a new contact is not found | Mentions were built before the person existed | mentions rebuild person-name |
| Words inside a file are not found | The file text was not extracted | attachments extract |
| A chat has no messages at all | The history was never downloaded | messages sync |
Next: Search efficiently shows how to pick the right command and narrow a search. For the stored columns behind these links, see the data model.
What gets indexed
Which kinds of content the tools make searchable (text, files, web pages, voice notes, pictures), what each needs, and what never leaves your computer.
Search efficiently
Choose the right search command, narrow before you search, page through results and keep the output small, with a table of common filters and the mistakes that cost a search.