agentgraph-server 0.7.2__tar.gz → 0.9.0__tar.gz

agentgraph_server-0.9.0/.agents/skills/agentgraph/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: agentgraph
+description: Use AgentGraph through its CLI or MCP tools to search and traverse selected local context, retrieve full source-backed evidence, fetch missing or stale resources, and troubleshoot connector availability.
+---
+
+# AgentGraph skill
+
+AgentGraph is a local graph of selected messages, documents, people, feeds, pages,
+and relationships. Use its CLI or connected MCP tools to investigate that context;
+do not query its database or connector internals directly.
+
+Prefer the connected MCP tools when AgentGraph is available through MCP. Use the
+`agentgraph` CLI when MCP is unavailable or when a terminal script is the natural
+interface. Do not query AgentGraph's SQLite database or connector internals directly.
+
+## Investigate
+
+1. Start with `search` for discovery. If the user supplied a graph ID, platform
+   reference, or indexed URL, use `get` directly instead.
+2. Read the full entity before making a source-backed claim. Search results and graph
+   traversals contain bounded snippets.
+3. Inspect direct edges or traverse only when relationships help answer the question.
+4. Resolve a stub or fetch a known resource when missing or stale content blocks the
+   answer, then repeat the read.
+5. Compare source dates and contents. Cite the source URL or entity ID and separate
+   source facts from conclusions drawn across sources.
+
+Use search filters when the type, source, author, time window, observation, or
+attachments are already known. A search without a query lists matching entities by
+date; a query ranks them by relevance.
+
+## Guardrails
+
+- A stub has neither a title nor content.
+- Use `source_created_at` and `source_updated_at` for source chronology; local
+  `created_at` and `updated_at` describe the graph record.
+- Browser observation alone updates `observed_at`; fetch, poll, and ingest do not
+  indicate that the user viewed a resource.
+- Check connector or authentication state only when availability, freshness, or a
+  graph operation calls it into question.
+- Confirm Person merges, deletion, credential removal, and removal of bookmark
+  protection with the user.
+- A multi-target deletion resolves every target before changing the graph; it either
+  deletes the resolved set or leaves the graph unchanged.
+
+## References
+
+- Read [references/commands.md](references/commands.md) for command syntax, MCP
+  mappings, filters, targets, stubs, and result limits.
+- Read [references/data-model.md](references/data-model.md) for entity types,
+  relationships, attachments, timestamps, and retention.
+- Read [references/operations.md](references/operations.md) for connector discovery,
+  authentication, fetching, downloads, polling, connector-owned commands, and server
+  transport.

{agentgraph_server-0.7.2 → agentgraph_server-0.9.0}/.agents/skills/agentgraph/references/commands.md

@@ -3,7 +3,7 @@
 ## CLI
 
 ```bash
-agentgraph search ["<query>"] [--type <type>] [--platform <platform>] [--filter key=value] [--since 12h|30m|2d] [--mine] [--has-attachments] [--limit N] [--order-by created_at|updated_at|source_created_at|source_updated_at|observed_at|synced_at] [--min-score N] [--json]
+agentgraph search [--type <type>] [--platform <platform>] [--filter key=value] [--since 12h|30m|2d] [--observed-since 12h|30m|2d] [--mine] [--has-attachments] [--limit N] [--order-by created_at|updated_at|source_created_at|source_updated_at|observed_at|synced_at] [--min-score N] [--json]
 agentgraph get <entity-id|platform/ref|url> [--resolve] [--json]
 agentgraph edges <entity-id|platform/ref> [--type <edge-type>] [--direction in|out|both] [--json]
 agentgraph traverse <entity-id|platform/ref> [--resolve] [--depth 0..4] [--json]
@@ -14,6 +14,11 @@ filter is applied as a hard constraint (`--limit` defaults to 10). Without one t
 is no ranking: the filters select the entities, `--order-by` sorts them newest first,
 `--min-score` is ignored, and `--limit` defaults to 50.
 
+`--since` filters `updated_at`; `--observed-since` filters browser observation time
+(`observed_at`), excluding never-observed entities. Both accept ISO timestamps or
+relative durations and include the cutoff itself. When supplied together, both
+must match. Neither flag changes ordering.
+
 `get` and `traverse` do not resolve stubs unless `--resolve` is supplied. Depth 0
 returns only the starting entity; depths 1 through 4 include that many relationship
 hops.
@@ -28,7 +33,7 @@ accept full UUIDs, unambiguous UUID prefixes, and platform references.
 ## MCP equivalents
 
 ```text
-agentgraph search ...    -> search_entities_tool(query, entity_types, platform, filters, since, authored_by_me, has_attachments, limit, order_by, min_score, refresh)
+agentgraph search ...    -> search_entities_tool(query, entity_types, platform, filters, since, authored_by_me, has_attachments, limit, order_by, min_score, refresh, observed_since)
 agentgraph get ...       -> get_entity_tool(entity_id, resolve)
 agentgraph edges ...     -> get_edges_tool(entity_id, edge_type, direction)
 agentgraph traverse ...  -> traverse_graph_tool(entity_id, max_depth, resolve)
@@ -38,6 +43,11 @@ MCP search defaults to `refresh=false`; set it only when fresh connector-owned
 presentation metadata is needed. It does not replace a targeted source fetch for
 stale content.
 
+MCP tools return structured content: successes use `status="ok"` with a `data`
+object; expected failures use `status="error"`, an error `code`, and `message`, with
+the MCP error flag set. Search `data` includes `has_more`; entity payloads include
+`is_stub` and, when known, `source_url`.
+
 ## Stubs
 
 An entity is a stub when it has neither a title nor content. With the CLI, pass

{agentgraph_server-0.7.2 → agentgraph_server-0.9.0}/.agents/skills/agentgraph/references/data-model.md

@@ -14,7 +14,12 @@
 | `Task` | Tracked work items such as Jira issues. Issue key, status, and assignee live in `metadata`. |
 | `Video` | Recorded videos such as Looms. The transcript is indexed as content and `metadata.web_url` links to the video. |
 
-The valid core model does not currently include `Project`.
+Installed connectors may add shared entity type names such as `Project`. The complete
+alphabetical catalog, including connector descriptions, is embedded in the
+`search_entities_tool` MCP description. With the CLI, connector-specific declarations
+are available from `agentgraph list-connectors --json`. Undeclared type strings remain
+storable and searchable for compatibility, but do not receive automatic discovery or
+reference routing.
 
 ## Relationships
 

{agentgraph_server-0.7.2 → agentgraph_server-0.9.0}/.agents/skills/agentgraph/references/operations.md

@@ -10,10 +10,17 @@ agentgraph auth remove <provider> [--account <account-id>] [--json]
 ```
 
 Use `agentgraph list-connectors --json` to discover installed connector source names,
-valid platform values, URL ownership, polling delegation, and sync state. Do not rely
-on a hardcoded platform list. Use `--verify` only when a live provider check is
+valid platform values, connector-declared entity types, URL ownership, polling
+delegation, and sync state. Do not rely on a hardcoded platform list. MCP clients
+receive the full installed entity type catalog in the `search_entities_tool`
+description during tool discovery. Use `--verify` only when a live provider check is
 needed.
 
+Connector `last_synced_at` values come from successful poll timestamps in `sync_state`,
+aggregated across account-scoped cursors. A connector command may reset its own cursor
+through the generic command-effects path; after a reset, its status is `never` until the
+next successful poll.
+
 MCP equivalents are `list_connectors_tool`, `list_auth_providers_tool`,
 `authenticate_provider_tool`, and `remove_auth_provider_tool`.
 
@@ -68,13 +75,15 @@ forms are `run_connector_command_tool("web", ["observe", "<url-or-prefix>"])` an
 ```bash
 agentgraph download <entity-id|platform/ref> [--output <file-or-dir>] [--json]
 agentgraph bookmark <entity-id|platform/ref|url> [--remove] [--json]
-agentgraph delete <entity-id|platform/ref|url> [--json]
+agentgraph delete <entity-id|platform/ref|url>... [--json]
 agentgraph unify-persons <primary-person-id> <duplicate-person-id>... [--json]
 ```
 
-Use `download_entity_tool`, `bookmark_entity_tool`, `delete_entity_tool`, and
-`unify_persons_tool` through MCP. Confirm identity before person unification. The
-first Person is canonical and keeps its ID. Deletion removes connected edges.
+Use `download_entity_tool`, `bookmark_entity_tool`, `delete_entity_tool`,
+`delete_entities_tool`, and `unify_persons_tool` through MCP. Confirm identity before
+person unification. The first Person is canonical and keeps its ID. Multi-target
+deletion resolves every target before deleting any of them, removes connected edges,
+and returns compact references for the deleted entities.
 
 ## Server and skill setup
 
@@ -86,12 +95,17 @@ The server listens on a Unix socket (`AGENTGRAPH_SERVER_UDS_PATH`, default
 `~/.agentgraph/agentgraph.sock`) as well as TCP, because most agent sandboxes deny
 loopback TCP while permitting an allowlisted socket.
 
-`agentgraph poll` and connector or authentication commands that queue a poll or ingest
-always contact that service and have no local fallback; if sandboxed execution blocks
-one, request permission to contact the server or ask for the socket to be allowlisted,
-then retry. Reads and `fetch`/`download` follow `AGENTGRAPH_QUERY_TRANSPORT`
-(`auto` by default: socket, then TCP, then in-process), so they keep working when the
-server is unreachable.
+CLI polling and connector or authentication commands that queue a poll or ingest
+contact the local server. Reads and `fetch`/`download` follow
+`AGENTGRAPH_QUERY_TRANSPORT` (`auto` by default: socket, then TCP, then in-process),
+so they keep working when the server is unreachable. The MCP server can run polling
+and ingest locally when it cannot queue them on the local server.
+
+Run ordinary reads with the default transport. To diagnose connectivity, use
+`AGENTGRAPH_QUERY_TRANSPORT=server agentgraph search x --limit 1`; retry an affected
+read with `AGENTGRAPH_QUERY_TRANSPORT=in-process` only after an actual sandbox
+connection failure. See the Coding agent sandboxes section of the configuration docs
+for Unix-socket allowlist settings.
 
 ```bash
 agentgraph mcp-config
@@ -99,9 +113,11 @@ agentgraph mcp-serve
 agentgraph install-skill [agentgraph] [--target user|project] [--no-claude] [--force] [--json]
 ```
 
-`agentgraph mcp-config` prints local stdio setup for ChatGPT Desktop Work Mode and
-Claude Desktop. In ChatGPT Desktop, enter the printed executable in **Command to
-launch** and `mcp-serve` in **Arguments**; for Claude Desktop, add the printed JSON
-to its MCP configuration file.
+`agentgraph mcp-config` prints local stdio setup for ChatGPT Desktop Work Mode, Codex,
+Claude Desktop, and Claude Code. Prefer these MCP connections when they are available.
+In ChatGPT Desktop, enter the printed executable in **Command to launch** and
+`mcp-serve` in **Arguments**; for Claude Desktop, add the printed JSON to its MCP
+configuration file. Claude Code uses the printed user-scoped command so the server is
+available across projects.
 
 The skill installer is available only through the `agentgraph install-skill` CLI command.

{agentgraph_server-0.7.2/agentgraph_server.egg-info → agentgraph_server-0.9.0}/PKG-INFO

@@ -1,18 +1,18 @@
 Metadata-Version: 2.4
 Name: agentgraph-server
-Version: 0.7.2
+Version: 0.9.0
 Summary: A local-first CLI and MCP server that turns selected digital sources into a searchable graph for the AI agent you already use.
 Requires-Python: >=3.12
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: aiosqlite>=0.20.0
-Requires-Dist: agentgraph-connector-web<0.7,>=0.5.5
+Requires-Dist: agentgraph-connector-web<0.8,>=0.7.0
 Requires-Dist: apscheduler>=3.11.2
 Requires-Dist: click<8.4
 Requires-Dist: fastapi>=0.135.2
 Requires-Dist: fastembed>=0.8.0
 Requires-Dist: httpx>=0.28.1
-Requires-Dist: mcp>=1.26.0
+Requires-Dist: mcp<2,>=1.26.0
 Requires-Dist: numpy>=2.4.6
 Requires-Dist: pydantic>=2.12.5
 Requires-Dist: pydantic-settings>=2.13.1
@@ -22,21 +22,21 @@ Requires-Dist: sqlite-vec>=0.1.9
 Requires-Dist: typer>=0.24.1
 Requires-Dist: uvicorn>=0.42.0
 Provides-Extra: google
-Requires-Dist: agentgraph-connector-google<0.7,>=0.5.5; extra == "google"
+Requires-Dist: agentgraph-connector-google<0.7,>=0.6.1; extra == "google"
 Provides-Extra: slack
-Requires-Dist: agentgraph-connector-slack<0.7,>=0.5.5; extra == "slack"
+Requires-Dist: agentgraph-connector-slack<0.7,>=0.6.1; extra == "slack"
 Provides-Extra: discord
-Requires-Dist: agentgraph-connector-discord<0.7,>=0.5.5; extra == "discord"
+Requires-Dist: agentgraph-connector-discord<0.7,>=0.6.1; extra == "discord"
 Provides-Extra: rss
-Requires-Dist: agentgraph-connector-rss<0.7,>=0.5.5; extra == "rss"
+Requires-Dist: agentgraph-connector-rss<0.8,>=0.7.0; extra == "rss"
 Provides-Extra: web
-Requires-Dist: agentgraph-connector-web<0.7,>=0.5.5; extra == "web"
+Requires-Dist: agentgraph-connector-web<0.8,>=0.7.0; extra == "web"
 Provides-Extra: all
-Requires-Dist: agentgraph-connector-web<0.7,>=0.5.5; extra == "all"
-Requires-Dist: agentgraph-connector-google<0.7,>=0.5.5; extra == "all"
-Requires-Dist: agentgraph-connector-slack<0.7,>=0.5.5; extra == "all"
-Requires-Dist: agentgraph-connector-discord<0.7,>=0.5.5; extra == "all"
-Requires-Dist: agentgraph-connector-rss<0.7,>=0.5.5; extra == "all"
+Requires-Dist: agentgraph-connector-web<0.8,>=0.7.0; extra == "all"
+Requires-Dist: agentgraph-connector-google<0.7,>=0.6.1; extra == "all"
+Requires-Dist: agentgraph-connector-slack<0.7,>=0.6.1; extra == "all"
+Requires-Dist: agentgraph-connector-discord<0.7,>=0.6.1; extra == "all"
+Requires-Dist: agentgraph-connector-rss<0.8,>=0.7.0; extra == "all"
 Dynamic: license-file
 
 # AgentGraph
@@ -122,7 +122,7 @@ Connect the agent you already use:
 agentgraph mcp-config
 ```
 
-Use the printed instructions to connect ChatGPT Desktop Work Mode or Claude Desktop to the local stdio server. See [Install](docs-src/install.md) for the complete setup path.
+Use the printed instructions to connect ChatGPT Desktop Work Mode, Codex, Claude Desktop, or Claude Code to the local stdio server. MCP is the preferred connection; the installed skill provides CLI fallback workflows. See [Install](docs-src/install.md) for the complete setup path.
 
 ## What AgentGraph is and is not
 

{agentgraph_server-0.7.2 → agentgraph_server-0.9.0}/README.md

@@ -81,7 +81,7 @@ Connect the agent you already use:
 agentgraph mcp-config
 ```
 
-Use the printed instructions to connect ChatGPT Desktop Work Mode or Claude Desktop to the local stdio server. See [Install](docs-src/install.md) for the complete setup path.
+Use the printed instructions to connect ChatGPT Desktop Work Mode, Codex, Claude Desktop, or Claude Code to the local stdio server. MCP is the preferred connection; the installed skill provides CLI fallback workflows. See [Install](docs-src/install.md) for the complete setup path.
 
 ## What AgentGraph is and is not
 

{agentgraph_server-0.7.2 → agentgraph_server-0.9.0}/agentgraph/backends/sqlite/backend.py

@@ -68,6 +68,7 @@ _LIST_PAGE_ORDER_BY = {
 }
 _COLUMN_FILTERS = {"platform", "platform_entity_id", "entity_type"}
 _FTS_DELETE_CHUNK_SIZE = 500
+_PLATFORM_ENTITY_ID_LOOKUP_CHUNK_SIZE = 900
 _BUSY_TIMEOUT_MS = 5_000
 _SCHEMA_VERSION = 6
 
@@ -116,6 +117,7 @@ def _entity_predicates(
     since: datetime | None = None,
     authored_by: list[str] | None = None,
     has_attachments: bool = False,
+    observed_since: datetime | None = None,
 ) -> tuple[str, list[Any], str, list[Any]]:
     """Build the entity-selection predicates shared by every leg of a search.
 
@@ -143,6 +145,9 @@ def _entity_predicates(
     if since:
         clauses.append("e.updated_at >= ?")
         params.append(_utc_stamp(since))
+    if observed_since:
+        clauses.append("e.observed_at >= ?")
+        params.append(_utc_stamp(observed_since))
     if has_attachments:
         clauses.append(
             "json_extract(e.metadata, '$.attachments') IS NOT NULL"
@@ -865,11 +870,14 @@ class SQLiteBackend(StorageBackend):
                     str(existing_row["content"]) if existing_row and existing_row["content"] else ""
                 )
                 fts_title = e.title if e.title is not None else existing_title
-                fts_content = e.content if e.content is not None else existing_content
+                fts_content = (
+                    e.content if e.content_searchable and e.content is not None else ""
+                )
                 rewrite_fts = (
                     existing_row is None
                     or fts_title != existing_title
-                    or fts_content != existing_content
+                    or (e.content_searchable and fts_content != existing_content)
+                    or not e.content_searchable
                 )
                 embedding = embeddings.get(e.platform_entity_id)
                 emb_blob = pack_embedding(embedding) if embedding else None
@@ -888,7 +896,10 @@ class SQLiteBackend(StorageBackend):
                     target_title = e.title if e.title is not None else existing_row["title"]
                     target_content = e.content if e.content is not None else existing_row["content"]
                     target_embedding = (
-                        emb_blob if emb_blob is not None else existing_row["content_embedding"]
+                        emb_blob if e.content_searchable and emb_blob is not None
+                        else existing_row["content_embedding"]
+                        if e.content_searchable
+                        else None
                     )
                     target_source_created = (
                         source_created
@@ -923,7 +934,7 @@ class SQLiteBackend(StorageBackend):
                         entity_type       = CASE WHEN entities.entity_type = 'Document' THEN EXCLUDED.entity_type ELSE entities.entity_type END,
                         title             = COALESCE(EXCLUDED.title, entities.title),
                         content           = COALESCE(EXCLUDED.content, entities.content),
-                        content_embedding = COALESCE(EXCLUDED.content_embedding, entities.content_embedding),
+                        content_embedding = CASE WHEN ? THEN COALESCE(EXCLUDED.content_embedding, entities.content_embedding) ELSE NULL END,
                         metadata          = EXCLUDED.metadata,
                         source_created_at = COALESCE(EXCLUDED.source_created_at, entities.source_created_at),
                         source_updated_at = COALESCE(EXCLUDED.source_updated_at, entities.source_updated_at),
@@ -949,6 +960,7 @@ class SQLiteBackend(StorageBackend):
                         local_updated,
                         e.retention_policy,
                         parent_id,
+                        e.content_searchable,
                         local_updated,
                     ],
                 )
@@ -1216,42 +1228,55 @@ class SQLiteBackend(StorageBackend):
 
     async def delete_entity(self, entity_id: str) -> EntityResult:
         """Delete one entity by internal ID. Edges cascade; FTS rows are removed explicitly."""
+        deleted = await self.delete_entities([entity_id])
+        return deleted[0]
+
+    async def delete_entities(self, entity_ids: list[str]) -> list[EntityResult]:
+        """Atomically delete entities, their edges, and their FTS rows."""
+        unique_ids = list(dict.fromkeys(entity_ids))
+        if not unique_ids:
+            raise ValueError("At least one entity ID is required")
         assert self._write_lock is not None
         async with self._write_lock:
             conn = self._conn_or_raise()
             await conn.execute("BEGIN IMMEDIATE")
             try:
-                await conn.execute(
-                    """
-                    UPDATE entities
-                    SET retention_parent_id = NULL, updated_at = ?
-                    WHERE retention_parent_id = ? AND bookmarked = 1
-                    """,
-                    [_now(), entity_id],
-                )
-                cursor = await conn.execute(
-                    """
-                    DELETE FROM entities
-                    WHERE id = ?
-                    RETURNING id, entity_type, platform, platform_entity_id,
-                              title, content, metadata, created_at, updated_at,
-                              source_created_at, source_updated_at, synced_at, observed_at,
-                              retention_policy, retention_parent_id,
-                              cumulative_observation_duration_ms, bookmarked
-                    """,
-                    [entity_id],
-                )
-                row = await cursor.fetchone()
-                if row is None:
-                    raise ValueError(f"Entity {entity_id!r} not found")
-                await conn.execute(
-                    "DELETE FROM entities_fts WHERE id NOT IN (SELECT id FROM entities)"
-                )
+                rows: list[aiosqlite.Row] = []
+                for start in range(0, len(unique_ids), _FTS_DELETE_CHUNK_SIZE):
+                    ids = unique_ids[start : start + _FTS_DELETE_CHUNK_SIZE]
+                    placeholders = ",".join("?" * len(ids))
+                    await conn.execute(
+                        f"""
+                        UPDATE entities
+                        SET retention_parent_id = NULL, updated_at = ?
+                        WHERE retention_parent_id IN ({placeholders}) AND bookmarked = 1
+                        """,
+                        [_now(), *ids],
+                    )
+                    cursor = await conn.execute(
+                        f"""
+                        DELETE FROM entities
+                        WHERE id IN ({placeholders})
+                        RETURNING id, entity_type, platform, platform_entity_id,
+                                  title, content, metadata, created_at, updated_at,
+                                  source_created_at, source_updated_at, synced_at, observed_at,
+                                  retention_policy, retention_parent_id,
+                                  cumulative_observation_duration_ms, bookmarked
+                        """,
+                        ids,
+                    )
+                    rows.extend(await cursor.fetchall())
+                    await conn.execute(
+                        f"DELETE FROM entities_fts WHERE id IN ({placeholders})", ids
+                    )
+                if len(rows) != len(unique_ids):
+                    raise ValueError("One or more entities were not found")
                 await conn.execute("COMMIT")
             except Exception:
                 await conn.execute("ROLLBACK")
                 raise
-        return _row_to_entity(row)
+        deleted_by_id = {str(row["id"]): _row_to_entity(row) for row in rows}
+        return [deleted_by_id[entity_id] for entity_id in unique_ids]
 
     # --- Read: entities ---
 
@@ -1269,6 +1294,7 @@ class SQLiteBackend(StorageBackend):
         has_attachments: bool = False,
         order_by: str | None = None,
         content_limit: int | None = None,
+        observed_since: datetime | None = None,
     ) -> list[EntityResult]:
         """Select entities by predicate, ranked by relevance or ordered by date.
 
@@ -1286,6 +1312,7 @@ class SQLiteBackend(StorageBackend):
             since,
             authored_by,
             has_attachments,
+            observed_since=observed_since,
         )
 
         if query_text is None or query_vec is None:
@@ -1540,6 +1567,30 @@ class SQLiteBackend(StorageBackend):
         )
         return _row_to_entity(row) if row else None
 
+    async def get_existing_platform_entity_ids(
+        self,
+        platform: str,
+        platform_entity_ids: list[str],
+    ) -> set[str]:
+        if not platform_entity_ids:
+            return set()
+
+        existing: set[str] = set()
+        for offset in range(0, len(platform_entity_ids), _PLATFORM_ENTITY_ID_LOOKUP_CHUNK_SIZE):
+            chunk = platform_entity_ids[
+                offset : offset + _PLATFORM_ENTITY_ID_LOOKUP_CHUNK_SIZE
+            ]
+            placeholders = ",".join("?" for _ in chunk)
+            rows = await self._fetchall(
+                f"""
+                SELECT platform_entity_id FROM entities
+                WHERE platform = ? AND platform_entity_id IN ({placeholders})
+                """,
+                [platform, *chunk],
+            )
+            existing.update(str(row["platform_entity_id"]) for row in rows)
+        return existing
+
     async def list_entities(
         self,
         entity_types: list[str] | None,
@@ -1986,6 +2037,9 @@ class SQLiteBackend(StorageBackend):
             [source, json.dumps(cursor), _now()],
         )
 
+    async def clear_cursor(self, source: str) -> None:
+        await self._execute("DELETE FROM sync_state WHERE source = ?", [source])
+
     # --- Connector support ---
 
     async def increment_observation_duration(
@@ -2123,6 +2177,26 @@ class SQLiteBackend(StorageBackend):
             result[row["platform"]] = datetime.fromisoformat(val) if val else None
         return result
 
+    async def get_sources_last_synced_at(
+        self, sources: list[str]
+    ) -> dict[str, datetime | None]:
+        if not sources:
+            return {}
+        rows = await self._fetchall(
+            "SELECT source, updated_at FROM sync_state"
+        )
+        result: dict[str, datetime | None] = dict.fromkeys(sources, None)
+        for source in sources:
+            matching = [
+                row["updated_at"]
+                for row in rows
+                if row["source"] == source or row["source"].startswith(f"{source}:")
+            ]
+            values = [datetime.fromisoformat(value) for value in matching if value]
+            if values:
+                result[source] = max(values)
+        return result
+
     async def reset_synced_at(self, platform: str, platform_entity_id: str) -> None:
         await self._execute(
             "UPDATE entities SET synced_at = NULL WHERE platform = ? AND platform_entity_id = ?",

{agentgraph_server-0.7.2 → agentgraph_server-0.9.0}/agentgraph/cli.py

@@ -437,6 +437,13 @@ def connector_command(
     try:
         result = type(connector).run_cli_command(command_args)
         effects = type(connector).command_effects(command_args, result)
+        if effects.reset_cursors:
+            from agentgraph.cli_query import run_graph_operation
+            from agentgraph.connectors.command_effects import execute_cursor_resets
+
+            result["reset_cursors"] = run_graph_operation(
+                lambda: execute_cursor_resets(effects)
+            )
         if effects.delete_entities:
             from agentgraph.cli_query import run_graph_operation
             from agentgraph.connectors.command_effects import execute_deletions
@@ -484,7 +491,7 @@ def list_connectors(
         False, "--verify", help="Live-check connector credentials with provider APIs"
     ),
 ) -> None:
-    """List installed connectors and their sync status."""
+    """List installed connectors, their resource entity types, and sync status."""
     from agentgraph.connectors.registry import bootstrap, get_all_connectors
     from agentgraph.connectors.status import connector_status_items
     from agentgraph.core.runtime import backend_context
@@ -505,6 +512,7 @@ def list_connectors(
     table = Table(title="Connectors", show_lines=True)
     table.add_column("Connector", style="bold", no_wrap=True)
     table.add_column("Description", ratio=1)
+    table.add_column("Types")
     table.add_column("Auth")
     table.add_column("Sync")
     table.add_column("Last sync", no_wrap=True)
@@ -513,6 +521,11 @@ def list_connectors(
         table.add_row(
             str(item["source"]),
             str(desc),
+            ", ".join(
+                str(definition["name"])
+                for definition in cast(list[dict[str, object]], item["entity_types"])
+            )
+            or "-",
             _connector_auth_label(item),
             str(item["sync"]),
             str(item["last_sync"]),
@@ -591,7 +604,7 @@ def search(
         None,
         "--since",
         "-s",
-        help="Only results after this time: ISO timestamp or relative (12h, 30m, 2d)",
+        help="Only results updated at or after this time: ISO timestamp or relative (12h, 30m, 2d)",
     ),
     mine: bool = typer.Option(False, "--mine", "-m", help="Only entities authored by me"),
     has_attachments: bool = typer.Option(
@@ -613,6 +626,11 @@ def search(
         0.03, "--min-score", help="Minimum relevance score (0–1); ignored without a query"
     ),
     json: bool = typer.Option(False, "--json", help="Output as JSON"),
+    observed_since: str | None = typer.Option(
+        None,
+        "--observed-since",
+        help="Only results observed at or after this time: ISO timestamp or relative (12h, 30m, 2d)",
+    ),
 ) -> None:
     """Search the knowledge graph, or list entities matching filters alone."""
     from agentgraph.cli_query import cmd_search
@@ -623,6 +641,7 @@ def search(
         platform=platform,
         filters=dict(f.split("=", 1) for f in filter if "=" in f),
         since=since,
+        observed_since=observed_since,
         authored_by_me=mine,
         has_attachments=has_attachments,
         limit=limit,
@@ -725,13 +744,13 @@ def bookmark(
 
 @app.command("delete")
 def delete_cmd(
-    target: str = typer.Argument(..., help="Entity ID, UUID prefix, platform ref, or URL"),
+    targets: list[str] = typer.Argument(..., help="Entity IDs, UUID prefixes, platform refs, or URLs"),
     json: bool = typer.Option(False, "--json", help="Output as JSON"),
 ) -> None:
-    """Delete an entity from the graph."""
+    """Delete one or more entities from the graph."""
     from agentgraph.cli_query import cmd_delete
 
-    cmd_delete(target=target, as_json=json)
+    cmd_delete(targets=targets, as_json=json)
 
 
 @app.command("unify-persons")
@@ -830,7 +849,7 @@ def mcp_config() -> None:
     typer.echo()
     typer.echo("Claude Code:")
     typer.echo("  Register the server from your terminal:\n")
-    typer.echo(f"  claude mcp add agentgraph -- {binary} mcp-serve")
+    typer.echo(f"  claude mcp add --transport stdio --scope user agentgraph -- {binary} mcp-serve")
     typer.echo()
     typer.echo("Every client above runs the same server. Reads follow")
     typer.echo("AGENTGRAPH_QUERY_TRANSPORT: by default the local server when one is")
@@ -874,7 +893,13 @@ def install_skill(
 
     typer.echo(f"Installed AgentGraph skill '{result.skill}' to {result.destination}")
     if result.claude_destination is not None:
-        typer.echo(f"Linked Claude skill to {result.claude_destination}")
+        if result.claude_linked:
+            typer.echo(f"Linked Claude skill to {result.claude_destination}")
+        else:
+            typer.echo(
+                f"Claude reads {result.claude_destination} already; "
+                "its skill directory is the same one."
+            )
 
 
 @app.command()

{agentgraph_server-0.7.2 → agentgraph_server-0.9.0}/agentgraph/cli_query.py

@@ -109,6 +109,7 @@ def cmd_search(
     authored_by_me: bool = False,
     has_attachments: bool = False,
     order_by: str | None = None,
+    observed_since: str | None = None,
 ) -> None:
     # An empty or whitespace-only argument is an absent query, not a query for
     # nothing: this keeps the limit default, the renderer, and the backend's
@@ -127,6 +128,7 @@ def cmd_search(
             platform,
             filters=filters,
             since=since,
+            observed_since=observed_since,
             authored_by_me=authored_by_me,
             has_attachments=has_attachments,
             order_by=order_by,
@@ -340,7 +342,22 @@ def cmd_bookmark(target: str, bookmarked: bool, as_json: bool) -> None:
     console.print(f"[green]{action}:[/green] {label} [{result['id'][:8]}]")
 
 
-def cmd_delete(target: str, as_json: bool) -> None:
+def cmd_delete(targets: list[str], as_json: bool) -> None:
+    if len(targets) == 1:
+        _cmd_delete_one(targets[0], as_json)
+        return
+
+    async def operation(client: QueryClient) -> dict[str, Any]:
+        return await client.delete_many(targets)
+
+    result = _run_with_client(operation)
+    if as_json:
+        console.print_json(json.dumps(result, default=str))
+        return
+    console.print(f"[green]Deleted {result['deleted_count']} entities.[/green]")
+
+
+def _cmd_delete_one(target: str, as_json: bool) -> None:
     async def operation(client: QueryClient) -> dict[str, Any]:
         return await client.delete(target)