feat: add contacts search plugin
This commit is contained in:
Peter Steinberger committed
1 parent
cab8dcf456
commit
0dc131e9f3
44 files changed
+1331
-448
No files matched your search
@@ -0,0 +1,45 @@
|
||||
---
|
||||
summary: "CLI reference for `clawdbot contacts` (unified contact graph)"
|
||||
read_when:
|
||||
- You want to list or link contacts across channels
|
||||
- You are using the contacts-search plugin
|
||||
---
|
||||
|
||||
# `clawdbot contacts`
|
||||
|
||||
Unified contact graph and identity linking.
|
||||
Provided by the [Contacts + Search plugin](/plugins/contacts-search).
|
||||
Concept overview: [Contact graph](/contact).
|
||||
|
||||
## Examples
|
||||
|
||||
```bash
|
||||
clawdbot contacts list
|
||||
clawdbot contacts list --query "sarah" --platform slack
|
||||
clawdbot contacts show <contact-id>
|
||||
clawdbot contacts search "alice"
|
||||
clawdbot contacts link <primary-id> <secondary-id>
|
||||
clawdbot contacts unlink slack U12345678
|
||||
clawdbot contacts suggestions
|
||||
clawdbot contacts auto-link --dry-run
|
||||
clawdbot contacts stats
|
||||
clawdbot contacts alias <contact-id> "Alias Name"
|
||||
clawdbot contacts alias <contact-id> "Old Alias" --remove
|
||||
```
|
||||
|
||||
## Commands
|
||||
|
||||
- `list`: list contacts (supports `--query`, `--platform`, `--limit`, `--json`).
|
||||
- `show <id>`: show a contact + identities (accepts a canonical id or a search query).
|
||||
- `search <query>`: search contacts by name/alias/username.
|
||||
- `link <primary> <secondary>`: merge two contacts.
|
||||
- `unlink <platform> <platformId>`: detach an identity into a new contact.
|
||||
- `suggestions`: show link suggestions.
|
||||
- `auto-link`: link high-confidence matches (use `--dry-run` to preview).
|
||||
- `stats`: store statistics by platform.
|
||||
- `alias <contactId> <alias>`: add or remove aliases (`--remove`).
|
||||
|
||||
## Notes
|
||||
|
||||
- `--platform` expects a channel id (e.g. `slack`, `discord`, `whatsapp`).
|
||||
- `unlink` uses the platform id stored on the identity (not the contact id).
|
||||
@@ -32,6 +32,8 @@ This page describes the current CLI behavior. If commands change, update this do
|
||||
- [`system`](/cli/system)
|
||||
- [`models`](/cli/models)
|
||||
- [`memory`](/cli/memory)
|
||||
- [`contacts`](/cli/contacts) (plugin; if enabled)
|
||||
- [`search`](/cli/search) (plugin; if enabled)
|
||||
- [`nodes`](/cli/nodes)
|
||||
- [`devices`](/cli/devices)
|
||||
- [`node`](/cli/node)
|
||||
@@ -122,6 +124,8 @@ clawdbot [--dev] [--profile <name>] <command>
|
||||
status
|
||||
index
|
||||
search
|
||||
contacts
|
||||
search
|
||||
message
|
||||
agent
|
||||
agents
|
||||
|
||||
@@ -0,0 +1,36 @@
|
||||
---
|
||||
summary: "CLI reference for `clawdbot search` (cross-platform message search)"
|
||||
read_when:
|
||||
- You want to search indexed messages across channels
|
||||
- You are using the contacts-search plugin
|
||||
---
|
||||
|
||||
# `clawdbot search`
|
||||
|
||||
Search indexed messages across channels.
|
||||
Provided by the [Contacts + Search plugin](/plugins/contacts-search).
|
||||
|
||||
## Examples
|
||||
|
||||
```bash
|
||||
clawdbot search "meeting tomorrow"
|
||||
clawdbot search "deadline" --from alice
|
||||
clawdbot search "project" --platform slack --since 1w
|
||||
clawdbot search "invoice" --since 2025-12-01 --until 2025-12-31
|
||||
clawdbot search "handoff" --limit 50 --json
|
||||
```
|
||||
|
||||
## Options
|
||||
|
||||
- `--from <contact>`: filter by sender name/alias/username or contact id.
|
||||
- `--platform <name>`: filter by channel id (e.g. `slack`, `discord`, `whatsapp`).
|
||||
- `--since <time>`: start time (`1h`, `2d`, `1w`, `1m`, or ISO date).
|
||||
- `--until <time>`: end time (same formats as `--since`).
|
||||
- `--limit <n>`: limit results (default `20`).
|
||||
- `--json`: raw JSON output.
|
||||
|
||||
## Notes
|
||||
|
||||
- Results come from the local contacts store (`~/.clawdbot/contacts/contacts.sqlite`).
|
||||
- Only inbound messages are indexed (no backfill).
|
||||
- Concept overview: [Contact graph](/contact).
|
||||
+100
@@ -0,0 +1,100 @@
|
||||
---
|
||||
summary: "Unified contacts: contact graph, identity linking, and message indexing"
|
||||
read_when:
|
||||
- You want to understand how Clawdbot merges identities across channels
|
||||
- You are using the Contacts + Search plugin
|
||||
---
|
||||
|
||||
# Contact graph
|
||||
|
||||
Clawdbot can maintain a **unified contact graph** that links the same person across multiple channels (Slack, Discord, WhatsApp, etc.).
|
||||
This powers cross-platform message search and manual identity linking.
|
||||
|
||||
The contact graph is provided by the **Contacts + Search** plugin and is **disabled by default**.
|
||||
|
||||
## Enable
|
||||
|
||||
Install/enable the plugin on the **Gateway host**, then restart the Gateway.
|
||||
|
||||
```bash
|
||||
clawdbot plugins enable contacts-search
|
||||
```
|
||||
|
||||
Config equivalent:
|
||||
|
||||
```json5
|
||||
{
|
||||
plugins: {
|
||||
entries: {
|
||||
"contacts-search": { enabled: true }
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Related:
|
||||
- [Contacts + Search plugin](/plugins/contacts-search)
|
||||
- [Plugins overview](/plugin)
|
||||
|
||||
## Data model
|
||||
|
||||
The contact graph has three layers:
|
||||
|
||||
1) **Canonical contact**
|
||||
- One logical person.
|
||||
- Has a `canonicalId`, display name, and optional aliases.
|
||||
|
||||
2) **Platform identity**
|
||||
- One account on one channel (e.g. `slack:U123...`).
|
||||
- Links back to a canonical contact.
|
||||
- Optional username, phone, display name, and last-seen time.
|
||||
|
||||
3) **Indexed message**
|
||||
- Text of inbound messages tied to a platform identity.
|
||||
- Used by cross-platform search.
|
||||
|
||||
## How contacts are created
|
||||
|
||||
Contacts are created automatically when **inbound messages** arrive:
|
||||
|
||||
- The plugin extracts sender identity details from the inbound message.
|
||||
- If the platform identity is new, a new canonical contact is created.
|
||||
- If it already exists, the identity metadata is refreshed.
|
||||
|
||||
There is **no backfill** step today; indexing starts when the plugin is enabled.
|
||||
|
||||
## Linking identities
|
||||
|
||||
You can link identities that belong to the same person:
|
||||
|
||||
- **Manual link**: merge two contacts into one canonical contact.
|
||||
- **Suggestions**: name/phone similarity hints (preview-only).
|
||||
- **Auto-link**: high-confidence matches (same phone number).
|
||||
|
||||
CLI reference: [Contacts CLI](/cli/contacts)
|
||||
|
||||
## Searching messages
|
||||
|
||||
Use the CLI or slash command:
|
||||
|
||||
- `clawdbot search "query"` (CLI)
|
||||
- `/search <query>` (chat)
|
||||
|
||||
Search uses SQLite FTS when available; otherwise it falls back to SQL `LIKE`.
|
||||
|
||||
CLI reference: [Search CLI](/cli/search)
|
||||
Slash commands: [Slash commands](/tools/slash-commands)
|
||||
|
||||
## Storage + privacy
|
||||
|
||||
- Stored locally on the Gateway host at `~/.clawdbot/contacts/contacts.sqlite`.
|
||||
- No cloud sync by default.
|
||||
- Treat this file as **sensitive** (names, handles, phone numbers).
|
||||
|
||||
To reset the graph, disable the plugin and move the SQLite file to Trash, then restart the Gateway.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
- **No results**: the plugin only indexes **new inbound messages**.
|
||||
- **Missing contacts**: ensure the plugin is enabled and the Gateway restarted.
|
||||
- **Search feels shallow**: FTS may be unavailable; check that SQLite FTS5 is supported on your runtime.
|
||||
@@ -848,6 +848,8 @@
|
||||
"cli/skills",
|
||||
"cli/plugins",
|
||||
"cli/memory",
|
||||
"cli/contacts",
|
||||
"cli/search",
|
||||
"cli/models",
|
||||
"cli/logs",
|
||||
"cli/system",
|
||||
@@ -883,6 +885,7 @@
|
||||
"concepts/session",
|
||||
"concepts/session-pruning",
|
||||
"concepts/sessions",
|
||||
"contact",
|
||||
"concepts/session-tool",
|
||||
"concepts/presence",
|
||||
"concepts/channel-routing",
|
||||
@@ -1003,6 +1006,7 @@
|
||||
"tools/lobster",
|
||||
"tools/llm-task",
|
||||
"plugin",
|
||||
"plugins/contacts-search",
|
||||
"plugins/voice-call",
|
||||
"plugins/zalouser",
|
||||
"tools/exec",
|
||||
|
||||
@@ -38,6 +38,7 @@ See [Voice Call](/plugins/voice-call) for a concrete example plugin.
|
||||
- Microsoft Teams is plugin-only as of 2026.1.15; install `@clawdbot/msteams` if you use Teams.
|
||||
- Memory (Core) — bundled memory search plugin (enabled by default via `plugins.slots.memory`)
|
||||
- Memory (LanceDB) — bundled long-term memory plugin (auto-recall/capture; set `plugins.slots.memory = "memory-lancedb"`)
|
||||
- [Contacts + Search](/plugins/contacts-search) — bundled unified contacts + cross-platform search (disabled by default)
|
||||
- [Voice Call](/plugins/voice-call) — `@clawdbot/voice-call`
|
||||
- [Zalo Personal](/plugins/zalouser) — `@clawdbot/zalouser`
|
||||
- [Matrix](/channels/matrix) — `@clawdbot/matrix`
|
||||
|
||||
@@ -0,0 +1,70 @@
|
||||
---
|
||||
summary: "Contacts + Search plugin: unified contacts and cross-platform message search"
|
||||
read_when:
|
||||
- You want unified contacts or cross-platform message search
|
||||
- You are enabling the contacts-search plugin
|
||||
---
|
||||
|
||||
# Contacts + Search (plugin)
|
||||
|
||||
Unified contact graph + cross-platform message search.
|
||||
Indexes incoming messages, links platform identities, and exposes `/search` plus CLI tools.
|
||||
|
||||
## What it adds
|
||||
|
||||
- `clawdbot contacts ...` (link, list, search, stats)
|
||||
- `clawdbot search ...` (message search)
|
||||
- `/search ...` slash command (text surfaces)
|
||||
|
||||
## Where it runs
|
||||
|
||||
Runs inside the Gateway process. Enable it on the **Gateway host**, then restart the Gateway.
|
||||
|
||||
## Enable (bundled)
|
||||
|
||||
```bash
|
||||
clawdbot plugins enable contacts-search
|
||||
```
|
||||
|
||||
Or in config:
|
||||
|
||||
```json5
|
||||
{
|
||||
plugins: {
|
||||
entries: {
|
||||
"contacts-search": { enabled: true }
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Restart the Gateway after enabling.
|
||||
|
||||
## Data location
|
||||
|
||||
The contact store lives under the Clawdbot state directory:
|
||||
|
||||
- `~/.clawdbot/contacts/contacts.sqlite`
|
||||
|
||||
If you run with `--profile <name>` or `--dev`, the state root changes accordingly.
|
||||
|
||||
## Indexing notes
|
||||
|
||||
- Messages are indexed as they arrive (no backfill).
|
||||
- Search uses SQLite FTS when available; otherwise falls back to SQL `LIKE` queries.
|
||||
|
||||
## CLI quickstart
|
||||
|
||||
```bash
|
||||
clawdbot contacts list
|
||||
clawdbot contacts search "sarah"
|
||||
clawdbot contacts show <contact-id>
|
||||
clawdbot search "meeting notes" --from sarah --since 1w
|
||||
```
|
||||
|
||||
Related:
|
||||
- CLI: [contacts](/cli/contacts)
|
||||
- CLI: [search](/cli/search)
|
||||
- Concept: [Contact graph](/contact)
|
||||
- Slash commands: [Slash commands](/tools/slash-commands)
|
||||
- Plugins: [Plugins](/plugin)
|
||||
@@ -61,7 +61,7 @@ Text + native (when enabled):
|
||||
- `/skill <name> [input]` (run a skill by name)
|
||||
- `/status` (show current status; includes provider usage/quota for the current model provider when available)
|
||||
- `/allowlist` (list/add/remove allowlist entries)
|
||||
- `/search <query> [--from <contact>] [--platform <name>] [--since <time>]` (search messages across platforms)
|
||||
- `/search <query> [--from <contact>] [--platform <name>] [--since <time>]` (search messages across platforms; requires [Contacts + Search](/plugins/contacts-search))
|
||||
- `/context [list|detail|json]` (explain "context"; `detail` shows per-file + per-tool + per-skill + system prompt size)
|
||||
- `/whoami` (show your sender id; alias: `/id`)
|
||||
- `/subagents list|stop|log|info|send` (inspect, stop, log, or message sub-agent runs for the current session)
|
||||
|
||||
Reference in new issue
Block a user