agentgraph-server 0.6.0__tar.gz → 0.7.0__tar.gz

{agentgraph_server-0.6.0/.agents/skills/AgentGraph → agentgraph_server-0.7.0/.agents/skills/agentgraph}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: AgentGraph
+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.
 ---
 
@@ -17,19 +17,33 @@ Use `agentgraph demo add` or `add_demo_tool` to add the fictional Atlas fixtures
 the configured graph. Remove them afterward with `agentgraph demo remove` or
 `remove_demo_tool`.
 
-## Commands that use localhost
+## Commands that use the local server
 
 `agentgraph poll` and connector or authentication commands that queue a poll or
-historical ingest call the configured local AgentGraph HTTP server. If a sandbox blocks
-one of these commands, request permission to contact that localhost server and retry
-the command after approval.
+historical ingest always call the local AgentGraph server. Reads (`search`, `get`,
+`edges`, `traverse`) and `fetch`/`download` use it when it is reachable and
+otherwise read the database directly, so they work with no server running.
+
+Many agent sandboxes deny loopback TCP but allow an allowlisted Unix socket, so the
+server listens on both and clients prefer the socket. If a command fails because the
+sandbox blocked it:
+
+- For `poll`, ingest, or auth commands there is no fallback — request permission to
+  contact the local server, or ask the user to allowlist the socket
+  (`~/.agentgraph/agentgraph.sock`), then retry.
+- For reads, `AGENTGRAPH_QUERY_TRANSPORT=in-process` bypasses the server entirely.
+- `AGENTGRAPH_QUERY_TRANSPORT=server agentgraph search x --limit 1` reports plainly
+  whether the server is reachable, instead of silently falling back.
+
+See the Coding agent sandboxes section of the configuration docs for the per-agent
+allowlist settings.
 
 ## Investigation workflow
 
 1. Discover likely entities with `agentgraph search "<query>" --json` or
    `search_entities_tool`.
 2. Open promising results with `agentgraph get <target> --json` or
-   `get_entity_tool` to read full content and source metadata. Search and query results
+   `get_entity_tool` to read full content and source metadata. Search results
    contain bounded snippets and set `content_truncated` when content was shortened.
 3. Follow relationships with `agentgraph edges`, `agentgraph traverse`,
    `get_edges_tool`, or `traverse_graph_tool`.
@@ -39,8 +53,11 @@ the command after approval.
    each source URL or entity identifier used.
 
 Start with search unless the user already supplied a graph ID, platform reference, or
-known indexed URL. Use structured `query` only when the entity type or filters are
-already known.
+known indexed URL. `search` covers both jobs: pass a query string for ranked
+discovery, and add or use only its filters (`--type`, `--platform`, `--filter`,
+`--since`, `--mine`, `--has-attachments`) when the entity type or constraints are
+already known. Omitting the query string turns it into a deterministic listing
+ordered by date.
 
 ## Context lifecycle
 

{agentgraph_server-0.6.0/.agents/skills/AgentGraph → agentgraph_server-0.7.0/.agents/skills/agentgraph}/references/commands.md

@@ -3,19 +3,23 @@
 ## CLI
 
 ```bash
-agentgraph search "<query>" [--type <type>] [--platform <platform>] [--limit N] [--min-score N] [--json]
-agentgraph query --type <entity-type> [--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] [--json]
+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 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]
 ```
 
+The query string is optional. With one, results are ranked by relevance and every
+filter is applied as a hard constraint (`--limit` defaults to 10). Without one there
+is no ranking: the filters select the entities, `--order-by` sorts them newest first,
+`--min-score` is ignored, and `--limit` defaults to 50.
+
 `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.
 
-Use `--json` when results will be parsed programmatically. Search and query return
-bounded content snippets with `content_truncated`; use `get` for the complete entity.
+Use `--json` when results will be parsed programmatically. Search returns bounded
+content snippets with `content_truncated`; use `get` for the complete entity.
 
 Targets accepted by `get` are full UUIDs, unambiguous UUID prefixes, platform
 references such as `slack/T123/C123`, and indexed HTTP(S) URLs. `edges` and `traverse`
@@ -24,16 +28,15 @@ accept full UUIDs, unambiguous UUID prefixes, and platform references.
 ## MCP equivalents
 
 ```text
-agentgraph search ...    -> search_entities_tool(query, entity_types, platform, limit, min_score, refresh)
-agentgraph query ...     -> query_by_filter_tool(entity_type, filters, since, authored_by_me, has_attachments, limit, order_by, refresh)
+agentgraph search ...    -> search_entities_tool(query, entity_types, platform, filters, since, authored_by_me, has_attachments, limit, order_by, min_score, refresh)
 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)
 ```
 
-MCP search and query default 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 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.
 
 ## Stubs
 

{agentgraph_server-0.6.0/.agents/skills/AgentGraph → agentgraph_server-0.7.0/.agents/skills/agentgraph}/references/data-model.md

@@ -11,8 +11,10 @@
 | `Message` | Chat messages. Chat images and uploads are stored in `metadata.attachments`. |
 | `Person` | Source identities and confirmed cross-source identity merges. |
 | `Spreadsheet` | Google Sheets and other spreadsheet resources. |
+| `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 `Task` or `Project`.
+The valid core model does not currently include `Project`.
 
 ## Relationships
 
@@ -25,7 +27,7 @@ context is sufficient and traversal when the investigation needs a bounded subgr
 Chat photos and file uploads are attachments on `Message` entities. Query them with:
 
 ```bash
-agentgraph query --type Message --has-attachments --since 7d --json
+agentgraph search --type Message --has-attachments --since 7d --json
 ```
 
 `metadata.attachments` is a JSON array containing `url`, `filename`, `content_type`,

{agentgraph_server-0.6.0/.agents/skills/AgentGraph → agentgraph_server-0.7.0/.agents/skills/agentgraph}/references/operations.md

@@ -3,13 +3,13 @@
 ## Availability and authentication
 
 ```bash
-agentgraph connectors [--verify] [--json]
+agentgraph list-connectors [--verify] [--json]
 agentgraph auth [--verify] [--json] status
 agentgraph auth <provider> [--add] [--account <account-id>]
 agentgraph auth remove <provider> [--account <account-id>] [--json]
 ```
 
-Use `agentgraph connectors --json` to discover installed connector source names,
+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
 needed.
@@ -30,8 +30,10 @@ agentgraph connector <source> --help
 The MCP equivalents are `fetch_entity_tool`, `fetch_entity_by_id_tool`,
 `poll_connectors_tool`, and `run_connector_command_tool`.
 
-Fetch persists the connector's complete returned batch before reporting counts and
-does not update `observed_at`. Poll reports `polled`, `already_running`, and `skipped`.
+Fetch persists the connector's complete returned batch before reporting entity,
+metadata-patch, person, and edge counts. Metadata patches record successful non-material
+refreshes without entity upsert events. Fetch does not update `observed_at`. Poll reports
+`polled`, `already_running`, and `skipped`.
 A connector can be refreshed by another connector, so also inspect `polled_by` and
 `sync` in connector status.
 
@@ -45,6 +47,22 @@ agentgraph connector gmail ingest [--account <account-id>] [--json]
 The MCP form is `run_connector_command_tool("gmail", ["ingest", ...])`. There is no
 top-level `agentgraph ingest` command or `ingest_connector_tool`.
 
+For an oversized HTML page, request a one-off web fetch that removes style, script,
+noscript, and comment blocks before applying the response-size limit:
+
+```bash
+agentgraph connector web fetch <url> --compact [--json]
+```
+
+The MCP form is `run_connector_command_tool("web", ["fetch", "<url>", "--compact"])`.
+Compaction applies only to that command; ordinary fetches, bookmarks, observations, and
+RSS article hydration retain their default behavior.
+
+Configure browser observation rules with `agentgraph connector web observe <url-or-prefix>`
+and remove them with `agentgraph connector web observe <url-or-prefix> --remove`. The MCP
+forms are `run_connector_command_tool("web", ["observe", "<url-or-prefix>"])` and
+`run_connector_command_tool("web", ["observe", "<url-or-prefix>", "--remove"])`.
+
 ## Files and retained context
 
 ```bash
@@ -64,14 +82,26 @@ first Person is canonical and keeps its ID. Deletion removes connected edges.
 process-management instructions rather than starting a duplicate foreground server
 when a service manager already owns it.
 
+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
-contact that service over localhost. If sandboxed execution blocks one of those
-commands, request permission to contact the configured localhost server and retry it.
+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.
 
 ```bash
 agentgraph mcp-config
 agentgraph mcp-serve
-agentgraph install-skill [AgentGraph] [--target user|project] [--no-claude] [--force] [--json]
+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.
+
 The skill installer is available only through the `agentgraph install-skill` CLI command.

{agentgraph_server-0.6.0 → agentgraph_server-0.7.0}/.agents/skills/slack-auth/SKILL.md

@@ -28,8 +28,10 @@ permission in the target workspace.
 Admins create AgentGraph at `https://api.slack.com/apps` with **Create New App →
 From an app manifest**, select the target workspace, paste the manifest printed by
 AgentGraph into Slack's **JSON** tab, approve it, and enter its Client ID. The
-manifest includes the only
-supported callback, `http://localhost:8766/slack/oauth/callback`.
+manifest includes the callback, which defaults to `http://localhost:8766/slack/oauth/callback`; set
+`AGENTGRAPH_SLACK_OAUTH_CALLBACK_PORT` before setup to use another local port. The
+manifest printed by AgentGraph uses that port, which must match the Slack app's
+registered redirect URL.
 
 Non-admins choose either **Enter a Client ID provided by a Slack admin** or **Set up
 the AgentGraph Slack App**. The setup path checks whether the target workspace

{agentgraph_server-0.6.0 → agentgraph_server-0.7.0}/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.4
 Name: agentgraph-server
-Version: 0.6.0
+Version: 0.7.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.6,>=0.5.0
+Requires-Dist: agentgraph-connector-web<0.7,>=0.5.5
 Requires-Dist: apscheduler>=3.11.2
 Requires-Dist: click<8.4
 Requires-Dist: fastapi>=0.135.2
@@ -16,26 +16,27 @@ Requires-Dist: mcp>=1.26.0
 Requires-Dist: numpy>=2.4.6
 Requires-Dist: pydantic>=2.12.5
 Requires-Dist: pydantic-settings>=2.13.1
+Requires-Dist: questionary>=2.1.1
 Requires-Dist: rich>=14.3.3
 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.6,>=0.5.0; extra == "google"
+Requires-Dist: agentgraph-connector-google<0.7,>=0.5.5; extra == "google"
 Provides-Extra: slack
-Requires-Dist: agentgraph-connector-slack<0.6,>=0.5.0; extra == "slack"
+Requires-Dist: agentgraph-connector-slack<0.7,>=0.5.5; extra == "slack"
 Provides-Extra: discord
-Requires-Dist: agentgraph-connector-discord<0.6,>=0.5.0; extra == "discord"
+Requires-Dist: agentgraph-connector-discord<0.7,>=0.5.5; extra == "discord"
 Provides-Extra: rss
-Requires-Dist: agentgraph-connector-rss<0.6,>=0.5.0; extra == "rss"
+Requires-Dist: agentgraph-connector-rss<0.7,>=0.5.5; extra == "rss"
 Provides-Extra: web
-Requires-Dist: agentgraph-connector-web<0.6,>=0.5.0; extra == "web"
+Requires-Dist: agentgraph-connector-web<0.7,>=0.5.5; extra == "web"
 Provides-Extra: all
-Requires-Dist: agentgraph-connector-web<0.6,>=0.5.0; extra == "all"
-Requires-Dist: agentgraph-connector-google<0.6,>=0.5.0; extra == "all"
-Requires-Dist: agentgraph-connector-slack<0.6,>=0.5.0; extra == "all"
-Requires-Dist: agentgraph-connector-discord<0.6,>=0.5.0; extra == "all"
-Requires-Dist: agentgraph-connector-rss<0.6,>=0.5.0; 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"
 Dynamic: license-file
 
 # AgentGraph
@@ -46,7 +47,7 @@ AgentGraph is a local-first, self-hosted CLI and MCP server that turns the sourc
 
 > **AgentGraph stores context; your agent reasons over it.** It is not an agent, chatbot, hosted graph service, or replacement for the tools you already use.
 
-[See the demo](docs-src/demo.md) · [Install](docs-src/install.md) · [Documentation](https://simonexmachina.github.io/agent-graph/) · [Chrome extension](https://chromewebstore.google.com/detail/agentgraph-extension/iilkfclglabllelhjacijldknapbhidi)
+[See the demo](docs-src/demo.md) · [Install](docs-src/install.md) · [Documentation](https://agentgraph.simonwa.de/) · [Chrome extension](https://chromewebstore.google.com/detail/agentgraph-extension/iilkfclglabllelhjacijldknapbhidi)
 
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="docs-src/assets/diagrams/architecture-overview-dark.svg">
@@ -110,7 +111,7 @@ agentgraph serve
 Install the [AgentGraph Chrome extension](https://chromewebstore.google.com/detail/agentgraph-extension/iilkfclglabllelhjacijldknapbhidi), browse a supported resource, then verify that context landed:
 
 ```bash
-agentgraph connectors
+agentgraph list-connectors
 agentgraph search "project kickoff notes"
 agentgraph traverse <entity-id> --depth 2
 ```
@@ -121,7 +122,7 @@ Connect the agent you already use:
 agentgraph mcp-config
 ```
 
-Use the printed stdio configuration with Claude Desktop, Claude Code, Codex, or another compatible MCP client. ChatGPT developer mode uses the streamable HTTP `/mcp` endpoint through HTTPS. See [Install](docs-src/install.md) for the complete setup path.
+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.
 
 ## What AgentGraph is and is not
 

{agentgraph_server-0.6.0 → agentgraph_server-0.7.0}/README.md

@@ -6,7 +6,7 @@ AgentGraph is a local-first, self-hosted CLI and MCP server that turns the sourc
 
 > **AgentGraph stores context; your agent reasons over it.** It is not an agent, chatbot, hosted graph service, or replacement for the tools you already use.
 
-[See the demo](docs-src/demo.md) · [Install](docs-src/install.md) · [Documentation](https://simonexmachina.github.io/agent-graph/) · [Chrome extension](https://chromewebstore.google.com/detail/agentgraph-extension/iilkfclglabllelhjacijldknapbhidi)
+[See the demo](docs-src/demo.md) · [Install](docs-src/install.md) · [Documentation](https://agentgraph.simonwa.de/) · [Chrome extension](https://chromewebstore.google.com/detail/agentgraph-extension/iilkfclglabllelhjacijldknapbhidi)
 
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="docs-src/assets/diagrams/architecture-overview-dark.svg">
@@ -70,7 +70,7 @@ agentgraph serve
 Install the [AgentGraph Chrome extension](https://chromewebstore.google.com/detail/agentgraph-extension/iilkfclglabllelhjacijldknapbhidi), browse a supported resource, then verify that context landed:
 
 ```bash
-agentgraph connectors
+agentgraph list-connectors
 agentgraph search "project kickoff notes"
 agentgraph traverse <entity-id> --depth 2
 ```
@@ -81,7 +81,7 @@ Connect the agent you already use:
 agentgraph mcp-config
 ```
 
-Use the printed stdio configuration with Claude Desktop, Claude Code, Codex, or another compatible MCP client. ChatGPT developer mode uses the streamable HTTP `/mcp` endpoint through HTTPS. See [Install](docs-src/install.md) for the complete setup path.
+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.
 
 ## What AgentGraph is and is not