agentgraph-server 0.5.1__tar.gz → 0.5.3__tar.gz

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

@@ -0,0 +1,76 @@
+---
+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.
+
+## 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.3/.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.3/.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.3/.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.3/PKG-INFO

@@ -0,0 +1,175 @@
+Metadata-Version: 2.4
+Name: agentgraph-server
+Version: 0.5.3
+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: 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: numpy>=2.4.6
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: pydantic-settings>=2.13.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"
+Provides-Extra: slack
+Requires-Dist: agentgraph-connector-slack<0.6,>=0.5.0; extra == "slack"
+Provides-Extra: discord
+Requires-Dist: agentgraph-connector-discord<0.6,>=0.5.0; extra == "discord"
+Provides-Extra: rss
+Requires-Dist: agentgraph-connector-rss<0.6,>=0.5.0; extra == "rss"
+Provides-Extra: web
+Requires-Dist: agentgraph-connector-web<0.6,>=0.5.0; 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"
+Dynamic: license-file
+
+# AgentGraph
+
+**Give the AI agent you already use a searchable world.**
+
+AgentGraph is a local-first, self-hosted CLI and MCP server that turns the sources you choose into a searchable graph for the AI agent you already use. Connect Gmail, Google Drive, Slack, Discord, RSS, and web pages; AgentGraph translates them into local entities, people, relationships, and searchable content.
+
+> **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)
+
+<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="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
+
+Coding agents work well because their source of truth is already on disk. They can search files, follow references, inspect history, and build a model of the system without the user pasting every relevant detail.
+
+The rest of a person's digital context is fragmented across messages, documents, feeds, and web pages. AgentGraph makes the parts you choose locally searchable and navigable through MCP, so a coding agent can investigate that context instead of starting every conversation blind.
+
+## How context enters the graph
+
+AgentGraph builds context in three ways:
+
+1. **Observe:** the Chrome extension recognizes a supported URL, waits until you have kept it focused for the observation threshold, and reports the resource to your local AgentGraph server. The owning connector fetches it through the source API.
+2. **Fetch:** your agent or the CLI can request a specific resource. The connector adds or refreshes its entities, people, and edges before returning.
+3. **Refresh:** connector polling and ingest keep configured or already-known resources current in the background.
+
+Observation is also an attention signal. Browser observation updates `observed_at`; direct fetch, polling, ingest, and source changes do not. Observable entities expire after 90 days by default unless they are observed again or bookmarked. See [How AgentGraph works](docs-src/how-it-works.md) and [Entity retention](docs-src/retention.md).
+
+The extension sends recognized URLs, plus the Gmail thread identifier where required, to the local server. It does not upload arbitrary page content to an AgentGraph-operated service.
+
+## Trace a decision across sources
+
+The launch demo asks an existing coding agent:
+
+> Before I reply to Maya, reconstruct the Atlas synchronization decision. What did she require, what did engineering agree, does the Drive plan match, and which research supports the decision? Flag contradictions and link every source.
+
+The agent uses the Graph skill and AgentGraph CLI to search a fictional Gmail thread, traverse a Slack discussion and its authors, check a stale Drive plan, and compare two research documents. Everything is included in one deterministic fixture; no provider credentials, browser observation, or MCP setup are required. [Run the demo](docs-src/demo.md).
+
+## What each connector makes perceptible
+
+| Connector | What it contributes | Context paths |
+| --- | --- | --- |
+| Gmail | Email threads, participants, subjects, bodies, and attachment references | Observe, fetch, poll, ingest |
+| Google Drive, Docs, Sheets | Folders, files, content, ownership, authorship, and containment | Observe, fetch, poll |
+| Slack | Channels and DMs, messages, replies, authors, mentions, and attachments | Observe, fetch, poll |
+| Discord | Channels, DMs, threads, messages, authors, mentions, and attachments | Observe, fetch, poll |
+| RSS | Feeds, posts, dates, authors, and publication relationships | Observe, fetch, poll, ingest |
+| Web | Configured pages and bookmarks with titles, text, metadata, and URLs | Observe, fetch |
+
+These connectors are proof of the pattern, not the boundary of the product. A connector can translate an API, export, webhook, local database, browser surface, or structured file into AgentGraph's shared model.
+
+**Bring any service into your agent's world.** Teams can keep private connectors for internal systems, individuals can connect niche tools, and open-source contributors can publish integrations for the wider community. See [Connectors](docs-src/connectors.md) and [Extending AgentGraph](docs-src/extending.md).
+
+## Quickstart
+
+AgentGraph requires Python 3.12+, [`uv`](https://docs.astral.sh/uv/), and Chrome for browser observation.
+
+```bash
+git clone https://github.com/simonexmachina/agent-graph
+cd agent-graph
+uv sync --extra all
+source .venv/bin/activate
+agentgraph onboard
+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 search "project kickoff notes"
+agentgraph traverse <entity-id> --depth 2
+```
+
+Connect the agent you already use:
+
+```bash
+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.
+
+## What AgentGraph is and is not
+
+| AgentGraph is | AgentGraph is not |
+| --- | --- |
+| Local-first infrastructure | An AI agent or autonomous assistant |
+| A CLI and MCP server | A replacement for your agent |
+| A searchable graph of selected context | A chatbot or LLM |
+| An open connector architecture | A hosted integration SaaS |
+| Semantic search plus typed entities and edges | Only a vector database |
+| Self-hosted and open source | A project-operated store for your graph data |
+
+## Local data and privacy
+
+Indexed content is stored in SQLite on your machine. Provider credentials stay in the AgentGraph config directory, and source API calls run directly from your machine under your credentials. AgentGraph does not operate a hosted graph service or send indexed content to a project-controlled backend.
+
+An MCP client you connect can receive content from the local graph, subject to that client's data practices. Read the complete [Privacy Policy](docs-src/privacy.md), [Terms of Service](docs-src/terms.md), and [retention model](docs-src/retention.md).
+
+## Interfaces
+
+| Surface | Use it for | Entry point |
+| --- | --- | --- |
+| MCP | Let an existing agent search, traverse, fetch, and manage context | `agentgraph mcp-config`, `agentgraph mcp-serve` |
+| CLI | Search, fetch, ingest, debug, and operate the graph | `agentgraph search`, `agentgraph fetch`, `agentgraph serve` |
+| Browser extension | Turn focused browsing on supported URLs into observations | [Chrome Web Store](https://chromewebstore.google.com/detail/agentgraph-extension/iilkfclglabllelhjacijldknapbhidi) |
+| Viewer | Inspect entities, people, relationships, and observation state | `http://127.0.0.1:8765/viewer` |
+
+## Documentation
+
+- [Install](docs-src/install.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)
+- [Commands](docs-src/commands/index.md)
+- [MCP tools](docs-src/mcp/index.md)
+- [Extending](docs-src/extending.md)
+
+## Contributing
+
+See [AGENTS.md](AGENTS.md) for repository-specific development rules. Before opening a change, run:
+
+```bash
+uv run pytest tests/ -m "not integration and not browser" -q
+uv run pyright
+uv run ruff check agentgraph/ packages/ scripts/ tests/
+```
+
+## License
+
+See [LICENSE](LICENSE).

agentgraph_server-0.5.3/README.md

@@ -0,0 +1,135 @@
+# AgentGraph
+
+**Give the AI agent you already use a searchable world.**
+
+AgentGraph is a local-first, self-hosted CLI and MCP server that turns the sources you choose into a searchable graph for the AI agent you already use. Connect Gmail, Google Drive, Slack, Discord, RSS, and web pages; AgentGraph translates them into local entities, people, relationships, and searchable content.
+
+> **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)
+
+<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="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
+
+Coding agents work well because their source of truth is already on disk. They can search files, follow references, inspect history, and build a model of the system without the user pasting every relevant detail.
+
+The rest of a person's digital context is fragmented across messages, documents, feeds, and web pages. AgentGraph makes the parts you choose locally searchable and navigable through MCP, so a coding agent can investigate that context instead of starting every conversation blind.
+
+## How context enters the graph
+
+AgentGraph builds context in three ways:
+
+1. **Observe:** the Chrome extension recognizes a supported URL, waits until you have kept it focused for the observation threshold, and reports the resource to your local AgentGraph server. The owning connector fetches it through the source API.
+2. **Fetch:** your agent or the CLI can request a specific resource. The connector adds or refreshes its entities, people, and edges before returning.
+3. **Refresh:** connector polling and ingest keep configured or already-known resources current in the background.
+
+Observation is also an attention signal. Browser observation updates `observed_at`; direct fetch, polling, ingest, and source changes do not. Observable entities expire after 90 days by default unless they are observed again or bookmarked. See [How AgentGraph works](docs-src/how-it-works.md) and [Entity retention](docs-src/retention.md).
+
+The extension sends recognized URLs, plus the Gmail thread identifier where required, to the local server. It does not upload arbitrary page content to an AgentGraph-operated service.
+
+## Trace a decision across sources
+
+The launch demo asks an existing coding agent:
+
+> Before I reply to Maya, reconstruct the Atlas synchronization decision. What did she require, what did engineering agree, does the Drive plan match, and which research supports the decision? Flag contradictions and link every source.
+
+The agent uses the Graph skill and AgentGraph CLI to search a fictional Gmail thread, traverse a Slack discussion and its authors, check a stale Drive plan, and compare two research documents. Everything is included in one deterministic fixture; no provider credentials, browser observation, or MCP setup are required. [Run the demo](docs-src/demo.md).
+
+## What each connector makes perceptible
+
+| Connector | What it contributes | Context paths |
+| --- | --- | --- |
+| Gmail | Email threads, participants, subjects, bodies, and attachment references | Observe, fetch, poll, ingest |
+| Google Drive, Docs, Sheets | Folders, files, content, ownership, authorship, and containment | Observe, fetch, poll |
+| Slack | Channels and DMs, messages, replies, authors, mentions, and attachments | Observe, fetch, poll |
+| Discord | Channels, DMs, threads, messages, authors, mentions, and attachments | Observe, fetch, poll |
+| RSS | Feeds, posts, dates, authors, and publication relationships | Observe, fetch, poll, ingest |
+| Web | Configured pages and bookmarks with titles, text, metadata, and URLs | Observe, fetch |
+
+These connectors are proof of the pattern, not the boundary of the product. A connector can translate an API, export, webhook, local database, browser surface, or structured file into AgentGraph's shared model.
+
+**Bring any service into your agent's world.** Teams can keep private connectors for internal systems, individuals can connect niche tools, and open-source contributors can publish integrations for the wider community. See [Connectors](docs-src/connectors.md) and [Extending AgentGraph](docs-src/extending.md).
+
+## Quickstart
+
+AgentGraph requires Python 3.12+, [`uv`](https://docs.astral.sh/uv/), and Chrome for browser observation.
+
+```bash
+git clone https://github.com/simonexmachina/agent-graph
+cd agent-graph
+uv sync --extra all
+source .venv/bin/activate
+agentgraph onboard
+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 search "project kickoff notes"
+agentgraph traverse <entity-id> --depth 2
+```
+
+Connect the agent you already use:
+
+```bash
+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.
+
+## What AgentGraph is and is not
+
+| AgentGraph is | AgentGraph is not |
+| --- | --- |
+| Local-first infrastructure | An AI agent or autonomous assistant |
+| A CLI and MCP server | A replacement for your agent |
+| A searchable graph of selected context | A chatbot or LLM |
+| An open connector architecture | A hosted integration SaaS |
+| Semantic search plus typed entities and edges | Only a vector database |
+| Self-hosted and open source | A project-operated store for your graph data |
+
+## Local data and privacy
+
+Indexed content is stored in SQLite on your machine. Provider credentials stay in the AgentGraph config directory, and source API calls run directly from your machine under your credentials. AgentGraph does not operate a hosted graph service or send indexed content to a project-controlled backend.
+
+An MCP client you connect can receive content from the local graph, subject to that client's data practices. Read the complete [Privacy Policy](docs-src/privacy.md), [Terms of Service](docs-src/terms.md), and [retention model](docs-src/retention.md).
+
+## Interfaces
+
+| Surface | Use it for | Entry point |
+| --- | --- | --- |
+| MCP | Let an existing agent search, traverse, fetch, and manage context | `agentgraph mcp-config`, `agentgraph mcp-serve` |
+| CLI | Search, fetch, ingest, debug, and operate the graph | `agentgraph search`, `agentgraph fetch`, `agentgraph serve` |
+| Browser extension | Turn focused browsing on supported URLs into observations | [Chrome Web Store](https://chromewebstore.google.com/detail/agentgraph-extension/iilkfclglabllelhjacijldknapbhidi) |
+| Viewer | Inspect entities, people, relationships, and observation state | `http://127.0.0.1:8765/viewer` |
+
+## Documentation
+
+- [Install](docs-src/install.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)
+- [Commands](docs-src/commands/index.md)
+- [MCP tools](docs-src/mcp/index.md)
+- [Extending](docs-src/extending.md)
+
+## Contributing
+
+See [AGENTS.md](AGENTS.md) for repository-specific development rules. Before opening a change, run:
+
+```bash
+uv run pytest tests/ -m "not integration and not browser" -q
+uv run pyright
+uv run ruff check agentgraph/ packages/ scripts/ tests/
+```
+
+## License
+
+See [LICENSE](LICENSE).

{agentgraph_server-0.5.1 → agentgraph_server-0.5.3}/agentgraph/auth/credentials.py

@@ -9,11 +9,20 @@ from __future__ import annotations
 import json
 import os
 import tempfile
+from pathlib import Path
 from typing import Any, cast
 
 from pydantic import BaseModel
 
-from agentgraph.config import CONFIG_DIR, CREDENTIALS_FILE
+from agentgraph.config import CONFIG_DIR, CREDENTIALS_FILE, get_config_paths
+
+
+def _credential_paths() -> tuple[Path, Path]:
+    """Resolve credentials dynamically while preserving local path overrides."""
+    if "AGENTGRAPH_CONFIG_DIR" in os.environ:
+        config_dir, _, _, credentials_file, _ = get_config_paths()
+        return config_dir, credentials_file
+    return CONFIG_DIR, CREDENTIALS_FILE
 
 
 class CredentialsFileError(ValueError):
@@ -26,34 +35,36 @@ class PlatformAccounts(BaseModel):
 
 
 def _load_all_credentials() -> dict[str, Any]:
-    if not CREDENTIALS_FILE.exists():
+    _, credentials_file = _credential_paths()
+    if not credentials_file.exists():
         return {}
     try:
-        data = json.loads(CREDENTIALS_FILE.read_text())
+        data = json.loads(credentials_file.read_text())
     except Exception as exc:
         # Never fall back to "no credentials" here: callers would treat a
         # damaged file as a first-time setup and overwrite every platform.
         raise CredentialsFileError(
-            f"Could not parse {CREDENTIALS_FILE}: {exc}. "
+            f"Could not parse {credentials_file}: {exc}. "
             "Fix or move the file aside, then re-run auth for each platform."
         ) from exc
     if not isinstance(data, dict):
         raise CredentialsFileError(
-            f"Expected a JSON object at the top level of {CREDENTIALS_FILE}, got {type(data).__name__}."
+            f"Expected a JSON object at the top level of {credentials_file}, got {type(data).__name__}."
         )
     return cast(dict[str, Any], data)
 
 
 def _write_all_credentials(raw: dict[str, Any]) -> None:
-    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    config_dir, credentials_file = _credential_paths()
+    config_dir.mkdir(parents=True, exist_ok=True)
     # Write via a temp file in the same directory and rename, so a concurrent
     # writer can never leave a shorter document overlaid on a longer one.
-    fd, tmp_name = tempfile.mkstemp(dir=CONFIG_DIR, prefix=".credentials-", suffix=".json")
+    fd, tmp_name = tempfile.mkstemp(dir=config_dir, prefix=".credentials-", suffix=".json")
     try:
         with os.fdopen(fd, "w") as handle:
             json.dump(raw, handle, indent=2, default=str)
         os.chmod(tmp_name, 0o600)
-        os.replace(tmp_name, CREDENTIALS_FILE)
+        os.replace(tmp_name, credentials_file)
     except BaseException:
         if os.path.exists(tmp_name):
             os.unlink(tmp_name)
@@ -64,8 +75,9 @@ def _validate_accounts(platform: str, val: dict[str, Any]) -> PlatformAccounts:
     try:
         return PlatformAccounts.model_validate(val)
     except Exception as exc:
+        _, credentials_file = _credential_paths()
         raise CredentialsFileError(
-            f"Stored '{platform}' credentials in {CREDENTIALS_FILE} are malformed: {exc}. "
+            f"Stored '{platform}' credentials in {credentials_file} are malformed: {exc}. "
             f"Fix the file or re-run auth for {platform}."
         ) from exc