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

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

@@ -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.1 → 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.1 → agentgraph_server-0.7.0}/.agents/skills/agentgraph/references/data-model.md

@@ -27,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.1 → agentgraph_server-0.7.0}/.agents/skills/agentgraph/references/operations.md

@@ -12,7 +12,7 @@ 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
-needed. Without `--json`, the CLI renders the same status as an operator-facing table.
+needed.
 
 MCP equivalents are `list_connectors_tool`, `list_auth_providers_tool`,
 `authenticate_provider_tool`, and `remove_auth_provider_tool`.
@@ -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.
 
@@ -80,9 +82,16 @@ 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_server-0.6.1 → agentgraph_server-0.7.0}/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.4
 Name: agentgraph-server
-Version: 0.6.1
+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.7,>=0.5.4
+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
@@ -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.4; extra == "google"
+Requires-Dist: agentgraph-connector-google<0.7,>=0.5.5; extra == "google"
 Provides-Extra: slack
-Requires-Dist: agentgraph-connector-slack<0.7,>=0.5.4; extra == "slack"
+Requires-Dist: agentgraph-connector-slack<0.7,>=0.5.5; extra == "slack"
 Provides-Extra: discord
-Requires-Dist: agentgraph-connector-discord<0.7,>=0.5.4; extra == "discord"
+Requires-Dist: agentgraph-connector-discord<0.7,>=0.5.5; extra == "discord"
 Provides-Extra: rss
-Requires-Dist: agentgraph-connector-rss<0.7,>=0.5.4; extra == "rss"
+Requires-Dist: agentgraph-connector-rss<0.7,>=0.5.5; extra == "rss"
 Provides-Extra: web
-Requires-Dist: agentgraph-connector-web<0.7,>=0.5.4; extra == "web"
+Requires-Dist: agentgraph-connector-web<0.7,>=0.5.5; extra == "web"
 Provides-Extra: all
-Requires-Dist: agentgraph-connector-web<0.7,>=0.5.4; extra == "all"
-Requires-Dist: agentgraph-connector-google<0.7,>=0.5.4; extra == "all"
-Requires-Dist: agentgraph-connector-slack<0.7,>=0.5.4; extra == "all"
-Requires-Dist: agentgraph-connector-discord<0.7,>=0.5.4; extra == "all"
-Requires-Dist: agentgraph-connector-rss<0.7,>=0.5.4; 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