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

{agentgraph_server-0.5.0 → agentgraph_server-0.5.2}/.agents/skills/graph/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: graph
-description: Use the AgentGraph CLI to query the local knowledge graph, inspect connectors, fetch entities, traverse relationships, and configure MCP access.
+description: Use the AgentGraph CLI to search and traverse the local knowledge graph, inspect sources, and retrieve evidence for coding-agent tasks.
 ---
 
 # /graph — AgentGraph CLI skill
@@ -23,7 +23,7 @@ agentgraph edges <entity-id|platform/ref> [--type <edge-type>] [--direction in|o
 agentgraph traverse <entity-id|platform/ref> --resolve [--depth N] [--json]
 
 # Filter entities by type and metadata
-agentgraph query --type <entity-type> [--filter key=value] [--since 12h|30m|2d] [--mine] [--has-attachments] [--limit N] [--order-by created_at|updated_at|last_accessed] [--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]
 
 # Trigger a connector fetch for a platform entity (by platform + platform-specific ID)
 agentgraph fetch <platform> <resource-id> [--json]
@@ -46,9 +46,6 @@ agentgraph unify-persons <primary-person-id> <duplicate-person-id>... [--json]
 # Queue a background poll for one or all connectors
 agentgraph poll [<source>] [--json]   # source: slack, gmail, discord, drive, rss — omit for all; reports already_running and skipped auth failures
 
-# Run a one-shot bulk ingest for a connector (all data within the retention window, beyond what poll covers)
-agentgraph ingest <source> [--json]   # e.g. gmail, rss
-
 # List installed connectors and their sync status; credential fields are null for connectors like RSS/web
 agentgraph connectors [--verify] [--json] # auth_provider, auth_status/auth_detail when applicable, auth_verified, url_patterns, polls, poll_delegates, polled_by, sync, last_synced_at
 
@@ -58,6 +55,7 @@ agentgraph connector <source> --help
 agentgraph connector rss add <feed-url> [feed-url...] [--json] # validates feeds, rejects non-feeds without saving, and queues an RSS poll
 agentgraph connector rss remove <feed-url> [feed-url...] [--json] # removes exact configured feed URLs
 agentgraph connector rss import-opml <file.opml> [--all | --select 1,3-5] [--json] # omit flags for checkbox selection
+agentgraph connector gmail ingest [--account <account-id>] [--json] # queue an optional 90-day Gmail historical backfill; omit --account for all authenticated Google accounts
 
 # Show credential-backed auth provider state (dedupes shared providers like Google); add --verify for live provider API checks
 agentgraph auth [--verify] [--json] status # provider, connectors[], auth_status/auth_detail, auth_verified, accounts[] including auth_method
@@ -75,6 +73,9 @@ agentgraph serve [--reload]
 agentgraph mcp-serve
 agentgraph mcp-config   # stdio config for Claude Desktop/Claude Code; ChatGPT uses a tunneled HTTPS /mcp endpoint
 
+# Create the self-contained fictional graph used by the public demo
+agentgraph demo seed --config-dir <directory> [--reset] [--json]
+
 # Install the bundled AgentGraph skill into ~/.agents/skills or ./.agents/skills
 agentgraph install-skill [graph] [--target user|project] [--force] [--json]
 ```
@@ -100,7 +101,6 @@ agentgraph fetch ...               -> fetch_entity_tool(platform, resource_id)
 agentgraph fetch-entity ...        -> fetch_entity_by_id_tool(entity_id)
 agentgraph download ...            -> download_entity_tool(entity_id, output_path)
 agentgraph poll [source]           -> poll_connectors_tool(source) # returns polled, already_running, and skipped lists
-agentgraph ingest <source>         -> ingest_connector_tool(source)
 agentgraph bookmark ...            -> bookmark_entity_tool(entity_id, bookmarked)
 agentgraph delete ...              -> delete_entity_tool(entity_id)
 agentgraph unify-persons ...       -> unify_persons_tool(primary_entity_id, duplicate_entity_ids)
@@ -112,7 +112,8 @@ agentgraph install-skill ...       -> install_skill_tool(skill, target, force)
 | Type | Contains |
 |---|---|
 | `Message` | Chat messages (Discord, Slack). **Chat images and file uploads are attachments on Message entities** — stored in `metadata.attachments` (JSON array with `url`, `filename`, `content_type`, `width`, `height`). Use `--has-attachments` to filter to messages with files. |
-| `Document` | Text documents (Google Docs, etc.) and Gmail attachment stubs. Gmail attachment stubs are referenced by their owning `Thread` and can be downloaded with `agentgraph download`. |
+| `Document` | Text documents (Google Docs, etc.) and Gmail attachment stubs. Gmail attachment stubs are referenced by their owning `Email` and can be downloaded with `agentgraph download`. |
+| `Email` | Gmail email threads. |
 | `Channel` | Chat channels and DM threads. |
 | `Task` | Tasks or to-do items. |
 | `Project` | Project/repository containers. |
@@ -139,10 +140,12 @@ agentgraph download <attachment-document-entity-id> --output <file-or-dir>
 - Delete targets accept: full UUID, UUID prefix, platform ref, or HTTP(S) URL. Connected edges are removed with the entity.
 - Use `agentgraph download` for source files stored behind connector auth, such as Drive PDFs, exported Google Docs/Sheets, or Gmail attachment `Document` stubs
 - `agentgraph fetch` and `agentgraph fetch-entity` persist the connector's complete returned batch before reporting counts; content-rich resources such as RSS feeds may take several minutes
-- Use `agentgraph bookmark` for entities or HTTP(S) URLs that should survive retention-window garbage collection
+- Direct fetch is not a browser observation and does not update `observed_at`; use it when a result references missing or stale context, not as evidence that the human viewed the resource
+- Use `agentgraph bookmark` for entities or HTTP(S) URLs that should survive retention-window expiration
 - Use `agentgraph unify-persons` only after confirming two or more `Person` entities are the same human; the first argument is the canonical person to keep. Without `--json`, the command displays the updated canonical Person, including merged identity metadata and duplicate identities.
 - `polls: false` does not always mean stale: check `polled_by` / `sync` for connectors refreshed by another connector, e.g. `gdocs` and `gsheets` are refreshed via the `gdrive` Drive Changes poll
 - Server logs go to stdout unless the process manager redirects them elsewhere
+- `agentgraph demo seed` is an offline CLI fixture; it does not configure or require an MCP client
 
 ## Stub Entities
 
@@ -151,9 +154,10 @@ An entity is a **stub** when it has no title and no content — it was reference
 ## Workflow
 
 When the user asks about graph data:
-1. Run `agentgraph connectors --json` to verify the relevant connector is installed and to inspect its last sync state
-2. Run `agentgraph auth --json status` to inspect local provider-level authentication state, especially for shared auth like Google
-3. If credential validity is uncertain, run `agentgraph auth --verify --json status` or `agentgraph connectors --verify --json` to live-check provider APIs for credential-backed connectors
-4. If Google has `auth_status: "invalid"` or `"missing"`, tell the user to run `agentgraph auth google`
-5. Run the appropriate `agentgraph` command with `--json` to get structured output
-6. Use `edges` or `traverse` to follow relationships when needed
+1. Search for the relevant terms with `agentgraph search ... --json`; do not query the SQLite database directly
+2. Open promising results with `agentgraph get ... --json` to read their full content and source metadata
+3. Use `agentgraph edges` or `agentgraph traverse` to follow people, threads, containers, references, and other relationships
+4. Compare source dates and contents, distinguish source facts from inference, and cite the source URLs or entity identifiers used
+5. Inspect `agentgraph connectors --json` and `agentgraph auth --json status` only when the task requires source freshness, a missing resource must be fetched, or a graph command reports a connector or credential problem
+6. If credential validity is uncertain, use `agentgraph auth --verify --json status` or `agentgraph connectors --verify --json`; if Google is invalid or missing, tell the user to run `agentgraph auth google`
+7. When a result links to an unfetched stub or a specific missing resource, use `fetch-entity` for its graph ID or `fetch <platform> <resource-id>`, then continue the investigation with the hydrated context

agentgraph_server-0.5.2/PKG-INFO

@@ -0,0 +1,175 @@
+Metadata-Version: 2.4
+Name: agentgraph-server
+Version: 0.5.2
+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) · [Quickstart](docs-src/quickstart.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.">
+</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. The [Quickstart](docs-src/quickstart.md) covers the complete path and expected result.
+
+## 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)
+- [Quickstart](docs-src/quickstart.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" -q
+uv run pyright
+uv run ruff check agentgraph/ packages/ scripts/ tests/
+```
+
+## License
+
+See [LICENSE](LICENSE).

agentgraph_server-0.5.2/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) · [Quickstart](docs-src/quickstart.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.">
+</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. The [Quickstart](docs-src/quickstart.md) covers the complete path and expected result.
+
+## 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)
+- [Quickstart](docs-src/quickstart.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" -q
+uv run pyright
+uv run ruff check agentgraph/ packages/ scripts/ tests/
+```
+
+## License
+
+See [LICENSE](LICENSE).

{agentgraph_server-0.5.0 → agentgraph_server-0.5.2}/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
 

{agentgraph_server-0.5.0 → agentgraph_server-0.5.2}/agentgraph/backends/__init__.py

@@ -15,6 +15,7 @@ from agentgraph.core.storage import StorageBackend
 logger = logging.getLogger(__name__)
 
 _registry: dict[str, type[StorageBackend]] = {}
+_builtin_import_errors: dict[str, ImportError] = {}
 
 
 def _ensure_loaded() -> None:
@@ -29,8 +30,9 @@ def _load_builtins() -> None:
         from agentgraph.backends.sqlite.backend import SQLiteBackend
 
         _registry["sqlite"] = SQLiteBackend
-    except ImportError:
-        logger.debug("SQLite backend unavailable (aiosqlite not installed)")
+    except ImportError as exc:
+        _builtin_import_errors["sqlite"] = exc
+        logger.debug("SQLite backend unavailable (aiosqlite not installed)", exc_info=True)
 
 
 def _load_plugins() -> None:
@@ -44,6 +46,11 @@ def _load_plugins() -> None:
 def get_backend_class(name: str) -> type[StorageBackend]:
     _ensure_loaded()
     if name not in _registry:
+        if name in _builtin_import_errors:
+            raise ValueError(
+                "SQLite backend is unavailable. Run this project with `uv run` or install "
+                "the project dependencies."
+            ) from _builtin_import_errors[name]
         raise ValueError(
             f"Unknown backend {name!r}. Available: {sorted(_registry)}"
         )