AgentGraph

AgentGraph is a local knowledge graph for AI agents. It indexes content from Slack, Discord, Gmail, Google Docs, Google Sheets, Google Drive, and RSS/Atom feeds into a queryable graph of entities, people, and relationships that you can use from the CLI, web viewer, browser extension, or MCP.

Docs

• Install
• Quickstart
• Configuration
• Performance testing
• Extending
• Commands
• MCP tools
• Privacy

Installation

Prerequisites

• Python 3.12+
• uv
• Chrome for the browser extension

Install uv if needed:

curl -LsSf https://astral.sh/uv/install.sh | sh

Clone and sync

git clone https://github.com/simonexmachina/agent-graph
cd agent-graph
uv sync --extra all

Or install only the connectors you need:

uv sync --extra google
uv sync --extra slack
uv sync --extra discord
uv sync --extra rss

Credentials and local state live in ~/.agentgraph/ by default, or under AGENTGRAPH_CONFIG_DIR if you set a custom config directory.

Quick Start

1. Authenticate connectors

Run the guided onboarding flow:

agentgraph onboard

Or authenticate a single source directly:

agentgraph auth <source>

2. Start AgentGraph

agentgraph serve

The default server URL is http://127.0.0.1:8765.

3. Install the browser extension

Install the AgentGraph Chrome Extension from the Chrome Web Store.

To build it locally instead:

cd extension
npm install
npm run build

Then open chrome://extensions, enable Developer Mode, click Load unpacked, and select extension/dist/.

4. Browse something supported

Open a Slack channel, Discord thread, Google Doc, Google Sheet, Gmail thread, or Drive folder and keep the tab focused long enough for the dwell threshold to trigger a fetch.

5. Verify entities landed

agentgraph connectors --json
agentgraph search "slack" --limit 5
agentgraph query --type Document --limit 5

6. Connect an assistant

agentgraph mcp-config

Use the printed stdio config with Claude Desktop or Claude Code. For ChatGPT developer mode, run AgentGraph with streamable HTTP and expose the local /mcp endpoint through HTTPS before creating the app/connector.

How It Works

The browser extension watches supported URLs and sends dwell events to your local AgentGraph server. When you stay on a page long enough, the matching connector fetches the resource and turns it into graph entities, people, and edges. After that first fetch, supported connectors keep known resources fresh with background polling.

Browser extension -> local server -> connector -> local graph
                                         |
                                         +-> CLI / viewer / MCP

AgentGraph is local-first. Indexed content is stored in a local SQLite database. The project does not run a hosted service for your graph data.

Surfaces

Surface	Use it for	Entry point
CLI	Search, fetch, ingest, debugging, and operations	agentgraph search, agentgraph fetch, agentgraph serve
MCP	Claude Desktop, Claude Code, ChatGPT developer mode, and other MCP clients	agentgraph mcp-config, agentgraph mcp-serve
Browser extension	Passive indexing from supported browser tabs	Chrome Web Store
Viewer	Visual graph inspection and manual exploration	http://127.0.0.1:8765/viewer

Commands

Query

agentgraph search "project kickoff notes"
agentgraph query --type Message --filter platform=slack --since 12h
agentgraph get <entity-id>
agentgraph edges <entity-id>
agentgraph traverse <entity-id> --depth 2

Fetch and files

agentgraph fetch gdocs <document-id>
agentgraph fetch-entity <entity-id>
agentgraph download <entity-id>
agentgraph bookmark <entity-id> --remove
agentgraph delete <entity-id>

Gmail attachments are indexed as Document stub entities referenced by the owning Thread. Re-fetch the thread, traverse one hop to find the attachment document, then pass that document ID to agentgraph download.

Sync and connectors

agentgraph connectors
agentgraph poll
agentgraph ingest gmail
agentgraph connector rss add https://example.com/feed.xml

MCP

agentgraph mcp-serve
agentgraph mcp-serve --transport sse --port 8808
agentgraph mcp-serve --transport streamable-http --host 0.0.0.0 --port 8808

ChatGPT uses the streamable HTTP endpoint, such as https://your-tunnel.example/mcp, not the stdio JSON config.

See the full command reference and MCP tool reference.

Connectors

Included connectors:

Source	Entities	Auth	Refresh model
Slack	Channel, Message	User OAuth PKCE; browser-session fallback	Browser dwell plus 5 minute polling
Discord	Channel, Message	Bot token	Browser dwell plus 5 minute polling
Google Docs	Document	Google OAuth	Browser dwell plus Drive-backed refresh
Google Sheets	Spreadsheet	Google OAuth	Browser dwell plus Drive-backed refresh
Google Drive	Folder, Document	Google OAuth	Browser dwell for folders and files, plus Drive changes polling
Gmail	Thread, Document stubs for attachments	Google OAuth	Browser dwell plus background poll and ingest
RSS	Folder, Document	Feed URLs	Background poll and ingest; add validates feeds and queues a poll

AgentGraph is designed to be extended. Custom connectors live in separate packages, register through the connector entry point, and implement the shared BaseConnector interface. See Extending.

Configuration

Settings are read from environment variables and from a .env file in the config directory.

Variable	Default	Description
AGENTGRAPH_CONFIG_DIR	~/.agentgraph	Directory for config, credentials, and the default SQLite database
AGENTGRAPH_BACKEND	sqlite	Persistence backend. The built-in backend is sqlite
AGENTGRAPH_BACKEND_SQLITE_PATH	$AGENTGRAPH_CONFIG_DIR/agentgraph.db	SQLite database path
AGENTGRAPH_SERVER_HOST	127.0.0.1	Server bind address
AGENTGRAPH_SERVER_PORT	8765	Server port
AGENTGRAPH_DWELL_THRESHOLD_SECONDS	3	Seconds of focus before a fetch is triggered
AGENTGRAPH_RETENTION_DAYS	90	Days before an unvisited entity is garbage collected
AGENTGRAPH_EMBEDDING_MODEL	BAAI/bge-small-en-v1.5	FastEmbed model used for embeddings
AGENTGRAPH_SLACK_CLIENT_ID	prompt/stored account	Optional Client ID override for the admin-created internal Slack OAuth app
AGENTGRAPH_SLACK_REDIRECT_URI	http://localhost:8766/slack/oauth/callback	Exact Slack OAuth callback registered on the app

See Configuration for the full setup.

MCP Tools

agentgraph mcp-serve exposes these tool families to MCP clients:

• list_connectors_tool
• list_auth_providers_tool
• authenticate_provider_tool
• run_connector_command_tool
• search_entities_tool
• get_entity_tool
• get_edges_tool
• traverse_graph_tool
• query_by_filter_tool
• fetch_entity_tool
• fetch_entity_by_id_tool
• download_entity_tool
• poll_connectors_tool
• ingest_connector_tool
• bookmark_entity_tool
• delete_entity_tool
• unify_persons_tool

Contributing

See AGENTS.md for repo-specific development rules.

Before opening a change, run:

uv run pytest tests/ -m "not integration" -q
uv run pyright
uv run ruff check agentgraph/

License

See LICENSE.