agentgraph-server 0.5.2__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.2/agentgraph_server.egg-info → agentgraph_server-0.5.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentgraph-server
-Version: 0.5.2
+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
@@ -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.3}/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/
 ```

{agentgraph_server-0.5.2 → agentgraph_server-0.5.3}/agentgraph/backends/sqlite/backend.py

@@ -63,6 +63,8 @@ _LIST_PAGE_ORDER_BY = {
 }
 _COLUMN_FILTERS = {"platform", "platform_entity_id", "entity_type"}
 _FTS_DELETE_CHUNK_SIZE = 500
+_BUSY_TIMEOUT_MS = 5_000
+_SCHEMA_VERSION = 2
 
 
 def _now() -> str:
@@ -126,36 +128,33 @@ class SQLiteBackend(StorageBackend):
 
         self._conn = await aiosqlite.connect(self._db_path, isolation_level=None)
         self._conn.row_factory = sqlite3.Row
-        if self._db_path == ":memory:":
-            self._read_conn = self._conn
-
-        if self._db_path != ":memory:":
-            await self._conn.execute("PRAGMA journal_mode=WAL")
-        await self._conn.execute("PRAGMA foreign_keys=ON")
-        legacy_table = await self._conn.execute(
-            "SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'entities'"
-        )
-        if await legacy_table.fetchone():
-            cursor = await self._conn.execute("PRAGMA table_info(entities)")
-            existing_columns = {row["name"] for row in await cursor.fetchall()}
-            if "observed_at" not in existing_columns:
-                await self._conn.execute("ALTER TABLE entities ADD COLUMN observed_at TEXT")
-        await self._conn.executescript(_SCHEMA_SQL)
-
-        await self._run_migrations()
-
-        if self._db_path != ":memory:":
-            self._read_conn = await aiosqlite.connect(self._db_path, isolation_level=None)
-            self._read_conn.row_factory = sqlite3.Row
-            await self._read_conn.execute("PRAGMA foreign_keys=ON")
-
-        if self._vector_mode == "sqlite-vec":
-            assert self._read_conn is not None
-            self._vec_loaded = await load_sqlite_vec(self._read_conn)
-            if self._vec_loaded:
-                logger.info("sqlite-vec extension loaded")
+        try:
+            await self._conn.execute(f"PRAGMA busy_timeout={_BUSY_TIMEOUT_MS}")
+            if self._db_path == ":memory:":
+                self._read_conn = self._conn
             else:
-                logger.info("sqlite-vec not available, falling back to numpy")
+                await self._ensure_wal_mode()
+            await self._conn.execute("PRAGMA foreign_keys=ON")
+
+            if await self._schema_version() < _SCHEMA_VERSION:
+                await self._initialize_schema()
+
+            if self._db_path != ":memory:":
+                self._read_conn = await aiosqlite.connect(self._db_path, isolation_level=None)
+                self._read_conn.row_factory = sqlite3.Row
+                await self._read_conn.execute(f"PRAGMA busy_timeout={_BUSY_TIMEOUT_MS}")
+                await self._read_conn.execute("PRAGMA foreign_keys=ON")
+
+            if self._vector_mode == "sqlite-vec":
+                assert self._read_conn is not None
+                self._vec_loaded = await load_sqlite_vec(self._read_conn)
+                if self._vec_loaded:
+                    logger.info("sqlite-vec extension loaded")
+                else:
+                    logger.info("sqlite-vec not available, falling back to numpy")
+        except Exception:
+            await self.close()
+            raise
 
     async def close(self) -> None:
         if self._read_conn is not None and self._read_conn is not self._conn:
@@ -178,6 +177,34 @@ class SQLiteBackend(StorageBackend):
 
     # --- Internal helpers ---
 
+    async def _ensure_wal_mode(self) -> None:
+        """Enable WAL once; reapplying it would take a write lock for every CLI read."""
+        conn = self._conn_or_raise()
+        cursor = await conn.execute("PRAGMA journal_mode")
+        row = await cursor.fetchone()
+        if row is None or str(row[0]).lower() != "wal":
+            await conn.execute("PRAGMA journal_mode=WAL")
+
+    async def _schema_version(self) -> int:
+        cursor = await self._conn_or_raise().execute("PRAGMA user_version")
+        row = await cursor.fetchone()
+        return int(row[0]) if row is not None else 0
+
+    async def _initialize_schema(self) -> None:
+        """Create or migrate a database once, before marking its schema version."""
+        conn = self._conn_or_raise()
+        legacy_table = await conn.execute(
+            "SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'entities'"
+        )
+        if await legacy_table.fetchone():
+            cursor = await conn.execute("PRAGMA table_info(entities)")
+            existing_columns = {row["name"] for row in await cursor.fetchall()}
+            if "observed_at" not in existing_columns:
+                await conn.execute("ALTER TABLE entities ADD COLUMN observed_at TEXT")
+        await conn.executescript(_SCHEMA_SQL)
+        await self._run_migrations()
+        await conn.execute(f"PRAGMA user_version={_SCHEMA_VERSION}")
+
     async def _run_migrations(self) -> None:
         conn = self._conn_or_raise()
         cursor = await conn.execute("PRAGMA table_info(entities)")
@@ -214,6 +241,7 @@ class SQLiteBackend(StorageBackend):
             or "source_updated_at" not in columns
             or "retention_policy" not in columns
             or "retention_parent_id" not in columns
+            or await self._retention_policy_needs_migration()
         )
         if needs_retention_migration:
             await self._rebuild_entities_for_retention(columns)
@@ -264,6 +292,14 @@ class SQLiteBackend(StorageBackend):
             "CREATE INDEX IF NOT EXISTS idx_entities_platform_type_observed_at ON entities(platform, entity_type, observed_at DESC)"
         )
 
+    async def _retention_policy_needs_migration(self) -> bool:
+        """Return whether the entity policy constraint lacks persistent support."""
+        cursor = await self._conn_or_raise().execute(
+            "SELECT sql FROM sqlite_master WHERE type = 'table' AND name = 'entities'"
+        )
+        row = await cursor.fetchone()
+        return row is None or "'persistent'" not in str(row["sql"])
+
     async def _rebuild_entities_for_retention(self, columns: set[str]) -> None:
         """Best-effort migration from source-based timestamps to lifecycle timestamps."""
         conn = self._conn_or_raise()
@@ -289,7 +325,10 @@ class SQLiteBackend(StorageBackend):
             source_updated = "updated_at" if "updated_at" in columns else "NULL"
 
         if "retention_policy" in columns:
-            retention_policy = "retention_policy"
+            retention_policy = (
+                "CASE WHEN platform = 'rss' AND entity_type = 'Folder' THEN 'persistent' "
+                "ELSE retention_policy END"
+            )
         else:
             retention_policy = (
                 "CASE entity_type WHEN 'Person' THEN 'connected' "
@@ -312,11 +351,15 @@ class SQLiteBackend(StorageBackend):
                 "CASE WHEN entity_type IN ('Channel', 'Document', 'Email', 'Folder', 'Spreadsheet') "
                 "AND cumulative_observation_duration_ms > 0 THEN observed_at ELSE NULL END"
             )
+        observed = (
+            "CASE WHEN platform = 'rss' AND entity_type = 'Folder' THEN NULL "
+            f"ELSE {observed} END"
+        )
         duration = "cumulative_observation_duration_ms" if "cumulative_observation_duration_ms" in columns else "0"
         bookmarked = "bookmarked" if "bookmarked" in columns else "0"
         await conn.execute("PRAGMA foreign_keys=OFF")
         try:
-            await conn.execute("BEGIN")
+            await conn.execute("BEGIN IMMEDIATE")
             await conn.execute(
                 """
                 CREATE TABLE entities_new (
@@ -335,7 +378,7 @@ class SQLiteBackend(StorageBackend):
                     synced_at TEXT,
                     observed_at TEXT,
                     retention_policy TEXT NOT NULL DEFAULT 'observed'
-                        CHECK (retention_policy IN ('observed', 'owned', 'connected')),
+                        CHECK (retention_policy IN ('observed', 'owned', 'connected', 'persistent')),
                     retention_parent_id TEXT REFERENCES entities_new(id) ON DELETE CASCADE,
                     cumulative_observation_duration_ms INTEGER NOT NULL DEFAULT 0,
                     bookmarked INTEGER NOT NULL DEFAULT 0,
@@ -436,7 +479,7 @@ class SQLiteBackend(StorageBackend):
                 persons=len(batch.persons),
                 edges=len(batch.edges),
             ):
-                await conn.execute("BEGIN")
+                await conn.execute("BEGIN IMMEDIATE")
                 try:
                     person_id_map = await self._upsert_persons(
                         conn, batch.persons, person_embeddings
@@ -860,7 +903,7 @@ class SQLiteBackend(StorageBackend):
         assert self._write_lock is not None
         async with self._write_lock:
             conn = self._conn_or_raise()
-            await conn.execute("BEGIN")
+            await conn.execute("BEGIN IMMEDIATE")
             try:
                 all_ids = [primary_entity_id, *duplicate_ids]
                 placeholders = ",".join("?" * len(all_ids))
@@ -1013,7 +1056,7 @@ class SQLiteBackend(StorageBackend):
         assert self._write_lock is not None
         async with self._write_lock:
             conn = self._conn_or_raise()
-            await conn.execute("BEGIN")
+            await conn.execute("BEGIN IMMEDIATE")
             try:
                 await conn.execute(
                     """
@@ -1583,7 +1626,7 @@ class SQLiteBackend(StorageBackend):
         assert self._write_lock is not None
         async with self._write_lock:
             conn = self._conn_or_raise()
-            await conn.execute("BEGIN")
+            await conn.execute("BEGIN IMMEDIATE")
             try:
                 before_cursor = await conn.execute("SELECT count(*) FROM entities")
                 before_row = await before_cursor.fetchone()
@@ -1706,7 +1749,7 @@ class SQLiteBackend(StorageBackend):
         async with self._write_lock:
             conn = self._conn_or_raise()
             now = _now()
-            await conn.execute("BEGIN")
+            await conn.execute("BEGIN IMMEDIATE")
             try:
                 cursor = await conn.execute(
                     """

{agentgraph_server-0.5.2 → agentgraph_server-0.5.3}/agentgraph/backends/sqlite/schema.sql

@@ -19,7 +19,7 @@ CREATE TABLE IF NOT EXISTS entities (
     synced_at          TEXT,  -- ISO8601 UTC
     observed_at        TEXT,
     retention_policy   TEXT NOT NULL DEFAULT 'observed'
-                       CHECK (retention_policy IN ('observed', 'owned', 'connected')),
+                       CHECK (retention_policy IN ('observed', 'owned', 'connected', 'persistent')),
     retention_parent_id TEXT REFERENCES entities(id) ON DELETE CASCADE,
     cumulative_observation_duration_ms INTEGER NOT NULL DEFAULT 0,
     bookmarked         INTEGER NOT NULL DEFAULT 0,

{agentgraph_server-0.5.2 → agentgraph_server-0.5.3}/agentgraph/cli.py

@@ -6,7 +6,6 @@ import asyncio
 import json as _json
 from collections.abc import Iterator
 from contextlib import contextmanager
-from pathlib import Path
 from typing import TYPE_CHECKING, cast
 
 import typer
@@ -53,19 +52,15 @@ def _status_label(status: str) -> str:
 
 @demo_app.command("seed")
 def seed_demo_command(
-    config_dir: Path = typer.Option(
-        ...,
-        "--config-dir",
-        help="Explicit non-default config directory for the isolated demo graph",
-    ),
-    reset: bool = typer.Option(False, "--reset", help="Replace an existing demo database"),
+    force: bool = typer.Option(False, "--force", help="Replace an existing demo database"),
     json: bool = typer.Option(False, "--json", help="Output as JSON"),
 ) -> None:
     """Seed the fictional Atlas graph used by the launch demo."""
+    from agentgraph.config import get_config_paths
     from agentgraph.demo import seed_demo
 
     try:
-        result = asyncio.run(seed_demo(config_dir, reset=reset))
+        result = asyncio.run(seed_demo(get_config_paths()[0], force=force))
     except (FileExistsError, ValueError) as exc:
         typer.echo(str(exc), err=True)
         raise typer.Exit(code=1) from exc
@@ -335,12 +330,17 @@ def connector_command(
     try:
         result = type(connector).run_cli_command(command_args)
         effects = type(connector).command_effects(command_args, result)
+        if effects.delete_entities:
+            from agentgraph.cli_query import run_graph_operation
+            from agentgraph.connectors.command_effects import execute_deletions
+
+            result["deleted_entities"] = run_graph_operation(lambda: execute_deletions(effects))
         if effects.poll:
-            from agentgraph.cli_query import queue_connector_poll
+            from agentgraph.cli_sync import queue_connector_poll
 
             result["poll"] = queue_connector_poll(connector.source)
         if effects.ingest:
-            from agentgraph.cli_query import queue_connector_ingest
+            from agentgraph.cli_sync import queue_connector_ingest
 
             result["ingest"] = queue_connector_ingest(
                 connector.source,
@@ -644,8 +644,17 @@ def mcp_config() -> None:
 
 @app.command()
 def install_skill(
-    skill: str = typer.Argument("graph", help="Bundled skill to install"),
-    target: str = typer.Option("user", "--target", help="Install target: user or project"),
+    skill: str = typer.Argument("AgentGraph", help="Bundled skill to install"),
+    target: str = typer.Option(
+        "user",
+        "--target",
+        help="Install target: user (~/.agents/skills) or project (./.agents/skills)",
+    ),
+    claude: bool = typer.Option(
+        True,
+        "--claude/--no-claude",
+        help="Link into Claude by default; --no-claude skips ~/.claude/skills or ./.claude/skills",
+    ),
     force: bool = typer.Option(False, "--force", help="Overwrite an existing installed skill"),
     json: bool = typer.Option(False, "--json", help="Output as JSON"),
 ) -> None:
@@ -658,7 +667,7 @@ def install_skill(
         raise typer.Exit(code=1)
 
     try:
-        result = install_agentgraph_skill(skill, target=target, force=force)
+        result = install_agentgraph_skill(skill, target=target, force=force, claude=claude)
     except SkillInstallError as exc:
         typer.echo(str(exc), err=True)
         raise typer.Exit(code=1) from exc
@@ -668,6 +677,8 @@ def install_skill(
         return
 
     typer.echo(f"Installed AgentGraph skill '{result.skill}' to {result.destination}")
+    if result.claude_destination is not None:
+        typer.echo(f"Linked Claude skill to {result.claude_destination}")
 
 
 @app.command()
@@ -710,7 +721,7 @@ def poll(
     json: bool = typer.Option(False, "--json", help="Output as JSON"),
 ) -> None:
     """Trigger a background poll for one or all connectors."""
-    from agentgraph.cli_query import cmd_poll
+    from agentgraph.cli_sync import cmd_poll
 
     cmd_poll(source=source, as_json=json)