agentgraph-server 0.5.2__tar.gz → 0.5.4__tar.gz

agentgraph_server-0.5.4/.agents/skills/AgentGraph/SKILL.md

@@ -0,0 +1,80 @@
+---
+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 CLI skill
+
+AgentGraph is a local knowledge graph for the agent the user already uses. It stores
+selected messages, documents, people, feeds, pages, and relationships; the agent is
+responsible for searching that graph, comparing evidence, and explaining its reasoning.
+
+Prefer the `agentgraph` CLI when a shell is available. Use the equivalent MCP tools
+when AgentGraph is connected directly to the agent. Do not query AgentGraph's SQLite
+database or connector internals directly.
+
+Use `agentgraph demo add` or `add_demo_tool` to add the fictional Atlas fixtures to
+the configured graph. Remove them afterward with `agentgraph demo remove` or
+`remove_demo_tool`.
+
+## Commands that use localhost
+
+`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.
+
+## 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
+   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`.
+4. If an entity is a stub, or known context is stale, resolve or re-fetch it through
+   the owning connector and then repeat the read or traversal.
+5. Compare source dates and contents. Distinguish source facts from inference and cite
+   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.
+
+## Context lifecycle
+
+- **Connect** is setup: installed connectors and their authentication/configuration
+  determine which selected sources AgentGraph can access.
+- **Observe** records human attention to a supported browser URL and triggers a
+  targeted connector fetch.
+- **Fetch** retrieves missing or stale context at the agent's request.
+- **Refresh** uses polling or connector-owned ingest commands to update configured or
+  already-known context.
+
+Only browser observation updates `observed_at`. Direct fetch, polling, and ingest can
+change graph content without implying that the human viewed it.
+
+## Evidence rules
+
+- Use full entity content before making a source-backed claim; do not treat a search
+  snippet as the complete source.
+- Treat an entity with no title and no content as an unresolved stub.
+- Use source timestamps for chronology. `created_at` and `updated_at` describe the
+  local graph record; `source_created_at` and `source_updated_at` describe the source.
+- Chat uploads live on `Message.metadata.attachments`. Gmail attachments are
+  `Document` stubs referenced by their owning `Email` and are downloaded separately.
+- Inspect connector and auth state only when freshness matters, a fetch is required,
+  or a graph operation reports a connector or credential problem.
+- Never merge Person entities without user confirmation. Treat delete, credential
+  removal, and unbookmarking as destructive actions.
+
+## References
+
+- Read [references/commands.md](references/commands.md) for CLI syntax, MCP mappings,
+  target formats, stub resolution, and result-size behavior.
+- Read [references/data-model.md](references/data-model.md) for entity types, edges,
+  attachment representation, timestamps, and retention semantics.
+- Read [references/operations.md](references/operations.md) for connectors, auth,
+  polling, connector-owned commands, downloads, bookmarks, deletion, person merging,
+  server setup, and skill installation.

agentgraph_server-0.5.4/.agents/skills/AgentGraph/references/commands.md

@@ -0,0 +1,45 @@
+# Query and traversal commands
+
+## 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 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]
+```
+
+`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.
+
+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`
+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 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.
+
+## Stubs
+
+An entity is a stub when it has neither a title nor content. With the CLI, pass
+`--resolve` to `get` or `traverse`. With MCP, set `resolve=true`, or call
+`fetch_entity_by_id_tool` for the stub UUID and repeat the original operation.
+
+For a known platform resource that is absent from the graph, use `agentgraph fetch
+<platform> <resource-id>` or `fetch_entity_tool(platform, resource_id)`.

agentgraph_server-0.5.4/.agents/skills/AgentGraph/references/data-model.md

@@ -0,0 +1,51 @@
+# AgentGraph data model
+
+## Entity types
+
+| Type | Contains |
+|---|---|
+| `Channel` | Chat channels and DM threads. |
+| `Document` | Text documents, feed/web pages, Drive files, and Gmail attachment stubs. |
+| `Email` | Gmail email threads. |
+| `Folder` | Drive folders and RSS feed containers. |
+| `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. |
+
+The valid core model does not currently include `Task` or `Project`.
+
+## Relationships
+
+Edges connect entities with types such as `authored`, `participated_in`, `posted_in`,
+`replied_to`, `mentions`, `contains`, and `references`. Use direct edges when one-hop
+context is sufficient and traversal when the investigation needs a bounded subgraph.
+
+## Attachments
+
+Chat photos and file uploads are attachments on `Message` entities. Query them with:
+
+```bash
+agentgraph query --type Message --has-attachments --since 7d --json
+```
+
+`metadata.attachments` is a JSON array containing `url`, `filename`, `content_type`,
+and optional `width` and `height` fields.
+
+Gmail attachments are different: they are `Document` stubs referenced by the owning
+`Email`. Re-fetch the email thread, traverse one hop, then download the attachment
+document.
+
+## Timestamps and retention
+
+- `created_at`: local graph insertion time.
+- `updated_at`: last material change to the stored entity.
+- `source_created_at`: source-reported creation or publication time.
+- `source_updated_at`: source-reported modification time.
+- `synced_at`: last successful connector synchronization.
+- `observed_at`: last accepted browser observation of that exact observable entity.
+
+Observable entities expire from `observed_at`, or local `created_at` if never
+observed. Messages and Gmail attachment documents follow their parent. Persons remain
+while connected. Configured RSS feed Folders are persistent source entities and are
+removed by the RSS connector's `remove` command or explicit deletion. Bookmarks protect
+an entity from automatic expiration.

agentgraph_server-0.5.4/.agents/skills/AgentGraph/references/operations.md

@@ -0,0 +1,77 @@
+# AgentGraph operations
+
+## Availability and authentication
+
+```bash
+agentgraph 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,
+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.
+
+MCP equivalents are `list_connectors_tool`, `list_auth_providers_tool`,
+`authenticate_provider_tool`, and `remove_auth_provider_tool`.
+
+## Fetch and refresh
+
+```bash
+agentgraph fetch <platform> <resource-id> [--json]
+agentgraph fetch-entity <entity-id> [--json]
+agentgraph poll [<source>] [--json]
+agentgraph connector <source> <command> [args...] [--json]
+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`.
+A connector can be refreshed by another connector, so also inspect `polled_by` and
+`sync` in connector status.
+
+Historical ingest is connector-owned. Discover it through connector help. For
+example, Gmail exposes:
+
+```bash
+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`.
+
+## Files and retained context
+
+```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 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.
+
+## Server and skill setup
+
+`agentgraph serve` runs the required local AgentGraph service. Follow the environment's
+process-management instructions rather than starting a duplicate foreground server
+when a service manager already owns it.
+
+`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.
+
+```bash
+agentgraph mcp-config
+agentgraph mcp-serve
+agentgraph install-skill [AgentGraph] [--target user|project] [--no-claude] [--force] [--json]
+```
+
+The skill installer is available only through the `agentgraph install-skill` CLI command.

{agentgraph_server-0.5.2/agentgraph_server.egg-info → agentgraph_server-0.5.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentgraph-server
-Version: 0.5.2
+Version: 0.5.4
 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
@@ -46,11 +46,11 @@ 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) · [Quickstart](docs-src/quickstart.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://simonexmachina.github.io/agent-graph/) · [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">
-  <img src="docs-src/assets/diagrams/architecture-overview-light.svg" alt="Selected online services connect to AgentGraph on the user's machine. Browser observation, agent fetches, and background refresh flow through connector packages into a local graph, which is exposed to the user's existing coding agent through MCP.">
+  <img src="docs-src/assets/diagrams/architecture-overview-light.svg" alt="Observe, Fetch, and Refresh converge on connector packages that read selected services and write to a local graph. Agents access the graph through the CLI or MCP, while Expiry applies the retention model.">
 </picture>
 
 ## Why AgentGraph
@@ -121,7 +121,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. The [Quickstart](docs-src/quickstart.md) covers the complete path and expected result.
+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.
 
 ## What AgentGraph is and is not
 
@@ -152,7 +152,7 @@ An MCP client you connect can receive content from the local graph, subject to t
 ## Documentation
 
 - [Install](docs-src/install.md)
-- [Quickstart](docs-src/quickstart.md)
+- [Install](docs-src/install.md)
 - [How AgentGraph works](docs-src/how-it-works.md)
 - [Connectors](docs-src/connectors.md)
 - [Configuration](docs-src/configuration.md)
@@ -165,7 +165,7 @@ An MCP client you connect can receive content from the local graph, subject to t
 See [AGENTS.md](AGENTS.md) for repository-specific development rules. Before opening a change, run:
 
 ```bash
-uv run pytest tests/ -m "not integration" -q
+uv run pytest tests/ -m "not integration and not browser" -q
 uv run pyright
 uv run ruff check agentgraph/ packages/ scripts/ tests/
 ```

{agentgraph_server-0.5.2 → agentgraph_server-0.5.4}/README.md

@@ -6,11 +6,11 @@ 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) · [Quickstart](docs-src/quickstart.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://simonexmachina.github.io/agent-graph/) · [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">
-  <img src="docs-src/assets/diagrams/architecture-overview-light.svg" alt="Selected online services connect to AgentGraph on the user's machine. Browser observation, agent fetches, and background refresh flow through connector packages into a local graph, which is exposed to the user's existing coding agent through MCP.">
+  <img src="docs-src/assets/diagrams/architecture-overview-light.svg" alt="Observe, Fetch, and Refresh converge on connector packages that read selected services and write to a local graph. Agents access the graph through the CLI or MCP, while Expiry applies the retention model.">
 </picture>
 
 ## Why AgentGraph
@@ -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. The [Quickstart](docs-src/quickstart.md) covers the complete path and expected result.
+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.
 
 ## What AgentGraph is and is not
 
@@ -112,7 +112,7 @@ An MCP client you connect can receive content from the local graph, subject to t
 ## Documentation
 
 - [Install](docs-src/install.md)
-- [Quickstart](docs-src/quickstart.md)
+- [Install](docs-src/install.md)
 - [How AgentGraph works](docs-src/how-it-works.md)
 - [Connectors](docs-src/connectors.md)
 - [Configuration](docs-src/configuration.md)
@@ -125,7 +125,7 @@ An MCP client you connect can receive content from the local graph, subject to t
 See [AGENTS.md](AGENTS.md) for repository-specific development rules. Before opening a change, run:
 
 ```bash
-uv run pytest tests/ -m "not integration" -q
+uv run pytest tests/ -m "not integration and not browser" -q
 uv run pyright
 uv run ruff check agentgraph/ packages/ scripts/ tests/
 ```