agentgraph-server 0.5.0__py3-none-any.whl

agentgraph/server/dwell.py

@@ -0,0 +1,79 @@
+"""Dwell dispatch: classifies a URL and fires a connector fetch."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from typing import Any
+
+from agentgraph.connectors.base import ResourceType
+from agentgraph.server.router import classify_observation_url
+
+logger = logging.getLogger(__name__)
+
+
+async def record_dwell_time(url: str, dwell_ms: int, meta: dict[str, str] | None = None) -> dict[str, Any]:
+    """Classify url and increment its cumulative dwell time in the backend."""
+    ref = await classify_observation_url(url)
+    if ref is None:
+        logger.debug("report-dwell: unrecognised URL %s", url)
+        return {"status": "ignored", "reason": "unrecognised URL"}
+
+    from agentgraph.config import get_settings
+    from agentgraph.core.context import get_backend
+
+    try:
+        backend = get_backend()
+        await backend.increment_dwell_time(ref.source, ref.resource_id, dwell_ms)
+        logger.debug(
+            "Recorded dwell time: +%dms for %s %s/%s",
+            dwell_ms, ref.source, ref.resource_type, ref.resource_id
+        )
+
+        # Dispatch background connector fetch if the dwell time meets the threshold
+        threshold_ms = get_settings().dwell_threshold_seconds * 1000
+        if dwell_ms >= threshold_ms:
+            logger.info(
+                "Dwell threshold met (%dms >= %dms): dispatching fetch for %s %s/%s",
+                dwell_ms, threshold_ms, ref.source, ref.resource_type, ref.resource_id
+            )
+            fetch_meta = dict(meta or {})
+            fetch_meta.update(ref.fetch_meta or {})
+            asyncio.create_task(
+                _dispatch(ref.source, ref.resource_type, ref.resource_id, fetch_meta or None)
+            )
+
+        return {"status": "accepted", "source": ref.source, "resource_type": ref.resource_type}
+    except Exception:
+        logger.exception("Failed to record dwell time for %s", url)
+        return {"status": "error", "reason": "internal backend error"}
+
+
+async def _dispatch(
+    source: str,
+    resource_type: ResourceType,
+    resource_id: str,
+    meta: dict[str, str] | None = None,
+) -> None:
+    from agentgraph.connectors.registry import get_connector
+
+    connector = get_connector(source)
+    if connector is None:
+        logger.debug("No connector registered for source '%s'", source)
+        return
+    try:
+        logger.info("Fetching %s/%s/%s", source, resource_type, resource_id)
+        batch = await connector.fetch(
+            resource_type=resource_type, resource_id=resource_id, meta=meta
+        )
+        if batch.entities or batch.persons or batch.edges:
+            from agentgraph.graph.upsert import upsert_batch
+
+            await upsert_batch(batch)
+        logger.info(
+            "Fetch complete %s/%s/%s — %d entities, %d persons, %d edges",
+            source, resource_type, resource_id,
+            len(batch.entities), len(batch.persons), len(batch.edges),
+        )
+    except Exception:
+        logger.exception("Connector fetch failed: %s/%s/%s", source, resource_type, resource_id)

agentgraph/server/graph_api.py

@@ -0,0 +1,46 @@
+"""Graph API router — admin endpoints."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from fastapi import APIRouter
+
+router = APIRouter(prefix="/api", tags=["graph"])
+
+
+@router.post("/admin/relink")
+async def relink_all() -> dict[str, Any]:
+    """Re-run URL reference linking for all entities that have content.
+
+    Creates stub entities for any classifiable URLs not yet in the graph.
+    Safe to call multiple times — uses ON CONFLICT DO NOTHING/UPDATE.
+    """
+    from agentgraph.core.context import get_backend
+    from agentgraph.graph.link import link_entity_to_urls
+
+    rows = await get_backend().list_entities(
+        entity_types=None,
+        platform=None,
+        since=None,
+        limit=100_000,
+    )
+
+    total_links = 0
+    for row in rows:
+        content = row.get("content")
+        platform = row.get("platform")
+        platform_entity_id = row.get("platform_entity_id")
+        if not (
+            isinstance(content, str)
+            and isinstance(platform, str)
+            and isinstance(platform_entity_id, str)
+        ):
+            continue
+        total_links += await link_entity_to_urls(
+            platform_entity_id,
+            platform,
+            content,
+        )
+
+    return {"relinked": len(rows), "edges_created": total_links}

agentgraph/server/router.py

@@ -0,0 +1,47 @@
+"""URL routing through connector-owned resolvers."""
+
+from __future__ import annotations
+
+import re
+
+from agentgraph.connectors.base import SourceReference
+
+# U+200B zero-width space, U+200C/D/E/F directional marks, U+00AD soft hyphen, U+FEFF BOM
+_INVISIBLE_CHARS_RE = re.compile(
+    "[­​‌‍‎‏]+"
+)
+
+
+def normalise_url_for_matching(url: str) -> str:
+    """Strip invisible characters and punctuation commonly wrapping URLs in prose."""
+    return _INVISIBLE_CHARS_RE.sub("", url).rstrip(".,)>\"'")
+
+
+def classify_url(url: str) -> SourceReference | None:
+    """Return a SourceReference for a connector-owned URL, or None."""
+    from agentgraph.connectors.registry import bootstrap, get_all_connectors
+
+    normalised_url = normalise_url_for_matching(url)
+    bootstrap()
+    for connector in get_all_connectors():
+        if type(connector).is_generic_url_fallback:
+            continue
+        ref = connector.resolve_url(normalised_url)
+        if ref is not None:
+            return ref
+    return None
+
+
+async def classify_observation_url(url: str) -> SourceReference | None:
+    """Resolve a browser-observed URL through connector-owned async resolvers."""
+    from agentgraph.connectors.registry import bootstrap, get_all_connectors
+
+    normalised_url = normalise_url_for_matching(url)
+    bootstrap()
+    for connector in get_all_connectors():
+        if type(connector).is_generic_url_fallback:
+            continue
+        ref = await connector.resolve_observation_url(normalised_url)
+        if ref is not None:
+            return ref
+    return None

agentgraph/server/sync.py

@@ -0,0 +1,247 @@
+"""SyncEngine: background polling for all connectors with poll_interval set."""
+
+# pyright: reportUnknownMemberType=false, reportUnknownVariableType=false
+# pyright: reportUnknownArgumentType=false
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from datetime import UTC, datetime, timedelta
+from time import perf_counter
+from typing import Literal, TypedDict, cast
+
+from apscheduler.schedulers.asyncio import AsyncIOScheduler  # type: ignore[import-untyped]
+
+from agentgraph.connectors.base import BaseConnector
+from agentgraph.connectors.status import connector_uses_auth
+from agentgraph.core.context import get_backend
+from agentgraph.graph.upsert import upsert_batch
+
+logger = logging.getLogger(__name__)
+
+_failure_counts: dict[str, int] = {}
+_backoff_until: dict[str, datetime] = {}
+_manual_poll_tasks: dict[str, asyncio.Task[None]] = {}
+_active_poll_tasks: dict[str, set[asyncio.Task[None]]] = {}
+
+
+PollScheduleStatus = Literal["queued", "already_running", "skipped"]
+
+
+class PollScheduleResult(TypedDict):
+    source: str
+    status: PollScheduleStatus
+    reason: str | None
+
+
+def clear_poll_backoff() -> None:
+    _failure_counts.clear()
+    _backoff_until.clear()
+    _manual_poll_tasks.clear()
+    _active_poll_tasks.clear()
+
+
+async def shutdown_poll_tasks(*, timeout: float = 10.0) -> None:
+    """Cancel in-flight poll tasks and wait briefly for their cleanup handlers."""
+    active_tasks = [task for tasks in _active_poll_tasks.values() for task in tasks]
+    tasks = {task for task in [*_manual_poll_tasks.values(), *active_tasks] if not task.done()}
+    if not tasks:
+        _manual_poll_tasks.clear()
+        _active_poll_tasks.clear()
+        return
+
+    for task in tasks:
+        task.cancel()
+    try:
+        await asyncio.wait_for(asyncio.gather(*tasks, return_exceptions=True), timeout=timeout)
+    except TimeoutError:
+        logger.warning("timed out waiting for %d poll task(s) to stop", len(tasks))
+    finally:
+        _manual_poll_tasks.clear()
+        _active_poll_tasks.clear()
+
+
+async def schedule_poll_connector(connector: BaseConnector) -> PollScheduleResult:
+    """Start a manual background poll unless one is already running."""
+    source = connector.source
+    existing = _manual_poll_tasks.get(source)
+    if existing is not None and not existing.done():
+        logger.info("poll %s — manual trigger skipped because a poll is already running", source)
+        return {"source": source, "status": "already_running", "reason": None}
+
+    auth_skip_reason = await _auth_skip_reason(connector)
+    if auth_skip_reason is not None:
+        logger.info("poll %s — manual trigger skipped: %s", source, auth_skip_reason)
+        return {"source": source, "status": "skipped", "reason": auth_skip_reason}
+
+    task = asyncio.create_task(poll_connector(connector))
+    _manual_poll_tasks[source] = task
+    task.add_done_callback(lambda done_task: _manual_poll_tasks.pop(source, None))
+    return {"source": source, "status": "queued", "reason": None}
+
+
+async def _auth_skip_reason(connector: BaseConnector) -> str | None:
+    if not connector_uses_auth(connector):
+        return None
+
+    try:
+        account_ids = connector.poll_account_ids()
+        statuses = [await type(connector).verify_auth(account_id) for account_id in account_ids]
+    except Exception as exc:
+        return f"authentication check failed: {type(exc).__name__}"
+
+    invalid = next(((status, detail) for status, detail in statuses if status == "invalid"), None)
+    if invalid is not None:
+        detail = invalid[1]
+        return f"authentication invalid: {detail}" if detail else "authentication invalid"
+
+    if not any(status == "ok" for status, _ in statuses):
+        return "authentication missing"
+
+    return None
+
+
+def _sync_scope(source: str, account_id: str | None) -> str:
+    return source if account_id is None else f"{source}:{account_id}"
+
+
+def _has_local_auth(connector: BaseConnector) -> bool:
+    if not connector_uses_auth(connector):
+        return True
+    accounts = type(connector).list_accounts()
+    if accounts:
+        return True
+    return type(connector).get_authenticated_user() is not None
+
+
+def _backoff_remaining(source: str) -> timedelta | None:
+    until = _backoff_until.get(source)
+    if until is None:
+        return None
+    remaining = until - datetime.now(UTC)
+    if remaining <= timedelta(0):
+        _backoff_until.pop(source, None)
+        return None
+    return remaining
+
+
+def _record_success(source: str) -> None:
+    _failure_counts.pop(source, None)
+    _backoff_until.pop(source, None)
+
+
+def _record_failure(source: str) -> None:
+    count = _failure_counts.get(source, 0) + 1
+    _failure_counts[source] = count
+    delay = min(60 * (2 ** (count - 1)), 3600)
+    _backoff_until[source] = datetime.now(UTC) + timedelta(seconds=delay)
+    logger.warning("poll %s — backing off for %ds after %d failure(s)", source, delay, count)
+
+
+async def poll_connector(connector: BaseConnector) -> None:
+    source = connector.source
+    task = cast(asyncio.Task[None] | None, asyncio.current_task())
+    if task is not None:
+        _active_poll_tasks.setdefault(source, set()).add(task)
+    started = perf_counter()
+    try:
+        remaining = _backoff_remaining(source)
+        if remaining is not None:
+            logger.info("poll %s — skipped during failure backoff (%.0fs remaining)", source, remaining.total_seconds())
+            return
+        if not _has_local_auth(connector):
+            logger.info("poll %s — skipped because authentication is not configured", source)
+            return
+        backend = get_backend()
+        for account_id in connector.poll_account_ids():
+            scope_started = perf_counter()
+            scope = _sync_scope(source, account_id)
+            cursor = await backend.load_cursor(scope)
+            is_first_run = not cursor
+            logger.info(
+                "poll %s — starting%s",
+                scope,
+                " (first run / bulk ingest)" if is_first_run else "",
+            )
+
+            batch, new_cursor = await connector.poll(cursor, account_id=account_id)
+
+            n_entities = len(batch.entities)
+            n_persons = len(batch.persons)
+            n_edges = len(batch.edges)
+
+            if batch.entities or batch.persons or batch.edges:
+                logger.info(
+                    "poll %s — upserting %d entities, %d persons, %d edges",
+                    scope, n_entities, n_persons, n_edges,
+                )
+                await upsert_batch(batch)
+                logger.info("poll %s — upsert complete", scope)
+            else:
+                logger.info("poll %s — no new data", scope)
+
+            await backend.save_cursor(scope, new_cursor)
+            logger.info("poll %s — completed in %.1fs", scope, perf_counter() - scope_started)
+        _record_success(source)
+    except Exception:
+        _record_failure(source)
+        logger.exception("poll failed for connector %s", source)
+    finally:
+        if task is not None:
+            tasks = _active_poll_tasks.get(source)
+            if tasks is not None:
+                tasks.discard(task)
+                if not tasks:
+                    _active_poll_tasks.pop(source, None)
+        logger.debug("poll %s total elapsed %.1fs", source, perf_counter() - started)
+
+
+async def run_ingest(connector: BaseConnector) -> None:
+    source = connector.source
+    started = perf_counter()
+    try:
+        for account_id in connector.poll_account_ids():
+            scope_started = perf_counter()
+            scope = _sync_scope(source, account_id)
+            logger.info("ingest %s — starting", scope)
+            batch = await connector.ingest(account_id=account_id)
+            if batch.entities or batch.persons or batch.edges:
+                logger.info(
+                    "ingest %s — upserting %d entities, %d persons, %d edges",
+                    scope, len(batch.entities), len(batch.persons), len(batch.edges),
+                )
+                await upsert_batch(batch)
+                logger.info("ingest %s — complete in %.1fs", scope, perf_counter() - scope_started)
+            else:
+                logger.info("ingest %s — no data returned", scope)
+    except Exception:
+        logger.exception("ingest failed for connector %s", source)
+    finally:
+        logger.debug("ingest %s total elapsed %.1fs", source, perf_counter() - started)
+
+
+def setup_sync(scheduler: AsyncIOScheduler) -> None:
+    """Register a poll job for every connector that has poll_interval set."""
+    from agentgraph.connectors.registry import get_all_connectors
+
+    for connector in get_all_connectors():
+        interval = connector.poll_interval
+        if interval is None:
+            continue
+        total_seconds = int(interval.total_seconds())
+        scheduler.add_job(
+            poll_connector,
+            "interval",
+            seconds=total_seconds,
+            args=[connector],
+            id=f"sync_{connector.source}",
+            name=f"poll connector {connector.source}",
+            max_instances=1,
+            coalesce=True,
+        )
+        logger.info(
+            "Scheduled background poll for %s every %ds",
+            connector.source,
+            total_seconds,
+        )

agentgraph/skills.py

@@ -0,0 +1,93 @@
+"""Install bundled AgentGraph skills into an agent skill directory."""
+
+from __future__ import annotations
+
+import shutil
+import sysconfig
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal
+
+SkillTarget = Literal["user", "project"]
+
+
+class SkillInstallError(ValueError):
+    """Raised when a skill cannot be installed."""
+
+
+@dataclass(frozen=True)
+class SkillInstallResult:
+    skill: str
+    target: SkillTarget
+    source: str
+    destination: str
+    overwritten: bool
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "skill": self.skill,
+            "target": self.target,
+            "source": self.source,
+            "destination": self.destination,
+            "overwritten": self.overwritten,
+        }
+
+
+def _bundled_skill_roots() -> list[Path]:
+    repo_root = Path(__file__).resolve().parents[1]
+    return [
+        repo_root / ".agents" / "skills",
+        Path(sysconfig.get_path("data")) / ".agents" / "skills",
+    ]
+
+
+def _find_source_skill(skill: str, source_root: Path | None) -> Path:
+    roots = [source_root] if source_root is not None else _bundled_skill_roots()
+    for root in roots:
+        candidate = root / skill
+        if (candidate / "SKILL.md").is_file():
+            return candidate
+
+    searched = ", ".join(str(root) for root in roots)
+    raise SkillInstallError(f"Skill {skill!r} was not found. Searched: {searched}")
+
+
+def _target_root(target: SkillTarget, project_dir: Path | None) -> Path:
+    if target == "user":
+        return Path.home() / ".agents" / "skills"
+    if target == "project":
+        return (project_dir or Path.cwd()) / ".agents" / "skills"
+    raise SkillInstallError("Target must be 'user' or 'project'")
+
+
+def install_skill(
+    skill: str = "graph",
+    *,
+    target: SkillTarget = "user",
+    force: bool = False,
+    source_root: Path | None = None,
+    project_dir: Path | None = None,
+) -> SkillInstallResult:
+    """Copy a bundled skill into the selected user or project skill directory."""
+    source = _find_source_skill(skill, source_root)
+    destination = _target_root(target, project_dir) / skill
+    overwritten = destination.exists()
+
+    if overwritten and not force:
+        raise SkillInstallError(
+            f"Skill {skill!r} already exists at {destination}. Use --force to overwrite it."
+        )
+
+    if overwritten:
+        shutil.rmtree(destination)
+
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    shutil.copytree(source, destination)
+
+    return SkillInstallResult(
+        skill=skill,
+        target=target,
+        source=str(source),
+        destination=str(destination),
+        overwritten=overwritten,
+    )

agentgraph_server-0.5.0.data/data/.agents/skills/graph/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: graph
+description: Use the AgentGraph CLI to query the local knowledge graph, inspect connectors, fetch entities, traverse relationships, and configure MCP access.
+---
+
+# /graph — AgentGraph CLI skill
+
+Use the `agentgraph` CLI to query the local knowledge graph. Always prefer the CLI over direct Python/DB access.
+
+## Commands
+
+```bash
+# Semantic search across entities
+agentgraph search "<query>" [--type <type>] [--platform <platform>] [--limit N] [--json]
+
+# Fetch full existing entity details by ID, UUID prefix, platform ref, or URL
+agentgraph get <entity-id|platform/ref|url> --resolve [--json]
+
+# List edges for an entity
+agentgraph edges <entity-id|platform/ref> [--type <edge-type>] [--direction in|out|both] [--json]
+
+# Traverse the graph from a starting entity
+agentgraph traverse <entity-id|platform/ref> --resolve [--depth N] [--json]
+
+# Filter entities by type and metadata
+agentgraph query --type <entity-type> [--filter key=value] [--since 12h|30m|2d] [--mine] [--has-attachments] [--limit N] [--order-by created_at|updated_at|last_accessed] [--json]
+
+# Trigger a connector fetch for a platform entity (by platform + platform-specific ID)
+agentgraph fetch <platform> <resource-id> [--json]
+
+# Trigger a connector re-fetch for an entity by its internal UUID
+agentgraph fetch-entity <entity-id> [--json]
+
+# Download an entity's source file using connector auth, including Gmail attachment Document stubs
+agentgraph download <entity-id|platform/ref> [--output <file-or-dir>] [--json]
+
+# Bookmark an entity or retrieve and bookmark an HTTP(S) URL; use --remove to clear bookmark protection
+agentgraph bookmark <entity-id|platform/ref|url> [--remove] [--json]
+
+# Delete an entity from the graph
+agentgraph delete <entity-id|platform/ref|url> [--json]
+
+# Merge duplicate Person entities that refer to the same human
+agentgraph unify-persons <primary-person-id> <duplicate-person-id>... [--json]
+
+# Queue a background poll for one or all connectors
+agentgraph poll [<source>] [--json]   # source: slack, gmail, discord, drive, rss — omit for all; reports already_running and skipped auth failures
+
+# Run a one-shot bulk ingest for a connector (all data within the retention window, beyond what poll covers)
+agentgraph ingest <source> [--json]   # e.g. gmail, rss
+
+# List installed connectors and their sync status; credential fields are null for connectors like RSS/web
+agentgraph connectors [--verify] [--json] # auth_provider, auth_status/auth_detail when applicable, auth_verified, url_patterns, polls, poll_delegates, polled_by, sync, last_synced_at
+
+# Run a connector-owned command
+agentgraph connector <source> <command> [args...] [--json] # e.g. agentgraph connector rss add https://simonwillison.net/atom/everything/
+agentgraph connector <source> --help
+agentgraph connector rss add <feed-url> [feed-url...] [--json] # validates feeds, rejects non-feeds without saving, and queues an RSS poll
+agentgraph connector rss remove <feed-url> [feed-url...] [--json] # removes exact configured feed URLs
+agentgraph connector rss import-opml <file.opml> [--all | --select 1,3-5] [--json] # omit flags for checkbox selection
+
+# Show credential-backed auth provider state (dedupes shared providers like Google); add --verify for live provider API checks
+agentgraph auth [--verify] [--json] status # provider, connectors[], auth_status/auth_detail, auth_verified, accounts[] including auth_method
+
+# Authenticate connectors/providers
+agentgraph auth google [--add] [--account <account-id>]   # uses AgentGraph's packaged OAuth client
+agentgraph auth slack [--method oauth|browser] [--client-id <client-id>] [--add] [--account <account-id>] # --client-id implies OAuth; without one, OAuth shows admin/app setup guidance
+agentgraph auth slack --method browser [--xoxc-token <token>] [--d-cookie <cookie>] # explicit browser-session fallback; credential flags imply browser
+agentgraph auth discord [--add] [--account <account-id>]  # Discord bot token
+agentgraph auth remove <provider> [--account <account-id>] [--json] # remove stored credentials; does not delete graph data
+agentgraph connector rss add <feed-url>                   # RSS/Atom feed URLs are connector configuration, not auth
+
+# Server
+agentgraph serve [--reload]
+agentgraph mcp-serve
+agentgraph mcp-config   # stdio config for Claude Desktop/Claude Code; ChatGPT uses a tunneled HTTPS /mcp endpoint
+
+# Install the bundled AgentGraph skill into ~/.agents/skills or ./.agents/skills
+agentgraph install-skill [graph] [--target user|project] [--force] [--json]
+```
+
+`--depth 0` returns only the requested entity; depths 1 through 4 include that many relationship hops.
+
+## MCP tool equivalents
+
+When using AgentGraph through MCP instead of the CLI, use these equivalent tools:
+
+```text
+agentgraph connectors              -> list_connectors_tool(verify)
+agentgraph auth [--json] status    -> list_auth_providers_tool(verify) # credential-backed providers only
+agentgraph auth <provider> ...     -> authenticate_provider_tool(provider, args, account_id, add)
+agentgraph auth remove ...         -> remove_auth_provider_tool(provider, account_id)
+agentgraph connector <source> ...  -> run_connector_command_tool(source, args)
+agentgraph search ...              -> search_entities_tool(...)
+agentgraph get ...                 -> get_entity_tool(entity_id)
+agentgraph edges ...               -> get_edges_tool(entity_id, edge_type, direction)
+agentgraph traverse ...            -> traverse_graph_tool(entity_id, max_depth)
+agentgraph query ...               -> query_by_filter_tool(...)
+agentgraph fetch ...               -> fetch_entity_tool(platform, resource_id)
+agentgraph fetch-entity ...        -> fetch_entity_by_id_tool(entity_id)
+agentgraph download ...            -> download_entity_tool(entity_id, output_path)
+agentgraph poll [source]           -> poll_connectors_tool(source) # returns polled, already_running, and skipped lists
+agentgraph ingest <source>         -> ingest_connector_tool(source)
+agentgraph bookmark ...            -> bookmark_entity_tool(entity_id, bookmarked)
+agentgraph delete ...              -> delete_entity_tool(entity_id)
+agentgraph unify-persons ...       -> unify_persons_tool(primary_entity_id, duplicate_entity_ids)
+agentgraph install-skill ...       -> install_skill_tool(skill, target, force)
+```
+
+## Entity types
+
+| Type | Contains |
+|---|---|
+| `Message` | Chat messages (Discord, Slack). **Chat images and file uploads are attachments on Message entities** — stored in `metadata.attachments` (JSON array with `url`, `filename`, `content_type`, `width`, `height`). Use `--has-attachments` to filter to messages with files. |
+| `Document` | Text documents (Google Docs, etc.) and Gmail attachment stubs. Gmail attachment stubs are referenced by their owning `Thread` and can be downloaded with `agentgraph download`. |
+| `Channel` | Chat channels and DM threads. |
+| `Task` | Tasks or to-do items. |
+| `Project` | Project/repository containers. |
+
+To find chat images uploaded this week: `agentgraph query --type Message --has-attachments --since 7d --json`
+
+To download a Gmail attachment: re-fetch the Gmail thread, traverse one hop to
+find referenced Gmail `Document` stubs, then download the attachment document:
+
+```bash
+agentgraph fetch-entity <gmail-thread-entity-id>
+agentgraph traverse <gmail-thread-entity-id> --depth 1 --json
+agentgraph download <attachment-document-entity-id> --output <file-or-dir>
+```
+
+## Notes
+
+- Graph data commands require the AgentGraph server. If a command reports the server is unavailable, run `agentgraph serve`.
+- Use `--json` when you need to parse results programmatically
+- List-style commands (`search`, `query`, and graph viewer/browse results) return bounded content snippets with `content_truncated` when applicable. Use `agentgraph get <entity-id> --json` for full entity content.
+- MCP `search_entities_tool` and `query_by_filter_tool` default to `refresh=false` so connector-owned network enrichment does not slow normal reads. Set `refresh=true` only when fresh connector-owned presentation metadata is needed.
+- Bookmark targets accept: full UUID, UUID prefix, platform ref (`slack/T123/C123`, `gdocs/doc-id`, `discord/dm/456`), or HTTP(S) URL
+- `agentgraph bookmark --remove <entity-id|platform/ref|url>` clears bookmark protection for existing graph entities
+- Delete targets accept: full UUID, UUID prefix, platform ref, or HTTP(S) URL. Connected edges are removed with the entity.
+- Use `agentgraph download` for source files stored behind connector auth, such as Drive PDFs, exported Google Docs/Sheets, or Gmail attachment `Document` stubs
+- `agentgraph fetch` and `agentgraph fetch-entity` persist the connector's complete returned batch before reporting counts; content-rich resources such as RSS feeds may take several minutes
+- Use `agentgraph bookmark` for entities or HTTP(S) URLs that should survive retention-window garbage collection
+- Use `agentgraph unify-persons` only after confirming two or more `Person` entities are the same human; the first argument is the canonical person to keep. Without `--json`, the command displays the updated canonical Person, including merged identity metadata and duplicate identities.
+- `polls: false` does not always mean stale: check `polled_by` / `sync` for connectors refreshed by another connector, e.g. `gdocs` and `gsheets` are refreshed via the `gdrive` Drive Changes poll
+- Server logs go to stdout unless the process manager redirects them elsewhere
+
+## Stub Entities
+
+An entity is a **stub** when it has no title and no content — it was referenced in an edge but never fetched from its source. Using `--resolve` (default for `get` and `traverse`) automatically fetches stubs from their source before returning. If you omitted `--resolve` and get empty results, re-run with it or use `agentgraph fetch-entity <entity-id>` then re-fetch.
+
+## Workflow
+
+When the user asks about graph data:
+1. Run `agentgraph connectors --json` to verify the relevant connector is installed and to inspect its last sync state
+2. Run `agentgraph auth --json status` to inspect local provider-level authentication state, especially for shared auth like Google
+3. If credential validity is uncertain, run `agentgraph auth --verify --json status` or `agentgraph connectors --verify --json` to live-check provider APIs for credential-backed connectors
+4. If Google has `auth_status: "invalid"` or `"missing"`, tell the user to run `agentgraph auth google`
+5. Run the appropriate `agentgraph` command with `--json` to get structured output
+6. Use `edges` or `traverse` to follow relationships when needed