chain-insights 0.2.31 → 0.2.32

package/docs/graph-tools.md

@@ -40,7 +40,10 @@ assumed to exist on the GraphRAG MCP endpoint.
 Agent installers ship two graph-query skills:
 
 - `chain-insights-cypher`: generic layer selection, schema capture, and
-  portable read-only GQL/Cypher examples.
+  portable read-only GQL/Cypher examples. Its
+  `references/memgraph-examples.md` file includes staging-tested Memgraph-style
+  recipes, archive/facts reads, and fixed-hop traversal fallbacks for native
+  Memgraph deep traversal syntax that the hosted GraphRAG MCP path may reject.
 - `chain-insights-bittensor-cypher`: Bittensor-specific schema notes for SS58
   and EVM-pallet addresses under `network=bittensor`.
 

package/docs/mcp-proxy.md

@@ -132,6 +132,11 @@ current caller's quota status. Public free access does not include
 usage and batches. Use explicit LIMIT and pagination in your query when you
 want bounded result sets.
 
+For custom graph reads, install the shipped `chain-insights-cypher` skill. Its
+Memgraph examples reference distinguishes staging-tested GraphRAG MCP query
+patterns from direct Memgraph deep traversal syntax that needs a fixed-hop
+`graph_query_batch` fallback through the hosted endpoint.
+
 Paid x402 mode:
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chain-insights",
-  "version": "0.2.31",
+  "version": "0.2.32",
   "description": "AML investigation CLI and MCP proxy for blockchain risk, fund-flow tracing, case reports, and GraphRAG MCP access",
   "homepage": "https://chain-insights.ai",
   "repository": {

package/skills/chain-insights-bittensor-cypher/SKILL.md

@@ -38,6 +38,14 @@ Observed against staging on 2026-05-29:
 - Source mappings include archive `STAKES_IN` and facts labels/features/neuron
   context, but staging returned generic backend errors for those sample reads;
   verify them with a fresh schema probe before relying on them.
+- On 2026-05-29, staging accepted practical Memgraph-style reads such as
+  `WHERE STARTS WITH`, `WITH` aggregations, `CASE`, address-family counts, and
+  fixed-hop `FLOWS_TO` patterns. It rejected native Memgraph deep traversal
+  operators through the hosted GraphRAG MCP path, including `*BFS`,
+  `*WSHORTEST`, `*ALLSHORTEST`, `*KSHORTEST`, and variable-length relationship
+  syntax. Use the generic skill reference
+  `references/memgraph-examples.md` for tested examples and fixed-hop
+  fallbacks.
 
 ## Bittensor Shapes
 
@@ -124,6 +132,22 @@ cia mcp call graph_query \
   'query=USE live_topology MATCH (src:Address {address: "FULL_BITTENSOR_ADDRESS"})-[flow:FLOWS_TO]->(dst:Address) RETURN dst.address AS to_address, flow.amount_sum AS amount_sum, flow.amount_usd_sum AS amount_usd_sum, flow.tx_count AS tx_count, flow.last_seen_timestamp AS last_seen_timestamp ORDER BY flow.amount_usd_sum DESC LIMIT 50'
 ```
 
+Find likely address completions from a prefix:
+
+```bash
+cia mcp call graph_query \
+  network=bittensor \
+  'query=USE live_topology MATCH (a:Address) WHERE a.address STARTS WITH "5Ggf" RETURN a.address AS address, a.address_type AS address_type, a.network AS network LIMIT 10'
+```
+
+Show how the combined Bittensor network currently splits address families:
+
+```bash
+cia mcp call graph_query \
+  network=bittensor \
+  'query=USE live_topology MATCH (a:Address) RETURN a.address_type AS address_type, a.network AS source_network, count(a) AS addresses ORDER BY addresses DESC LIMIT 10'
+```
+
 Historical archive read for the same address:
 
 ```bash

package/skills/chain-insights-cypher/SKILL.md

@@ -21,6 +21,11 @@ skill exists, load it after this one.
 4. Use `graph_query_batch` for related schema, topology, and facts reads.
 5. Save material query output as workspace evidence before summarizing it.
 
+For practical query recipes and Memgraph deep traversal fallbacks, read
+`references/memgraph-examples.md`. It contains staging-tested examples for
+`MATCH`, `WHERE`, `WITH`, aggregates, `CASE`, archive/facts projections, and
+fixed-hop traversal batches.
+
 ## Layer Choice
 
 | Layer | Use for | Query style |
@@ -32,7 +37,9 @@ skill exists, load it after this one.
 Treat `archive_topology` and `facts` as mapped graph views, not full Memgraph.
 Avoid backend-specific functions such as `keys()`, `labels()`, `type()`,
 procedures, native BFS syntax, catalog operations, and variable-length path
-tricks unless the current endpoint has just accepted the exact pattern.
+tricks unless the current endpoint has just accepted the exact pattern. When a
+Memgraph deep traversal pattern fails, rewrite it as a bounded
+`graph_query_batch` of explicit fixed-hop `FLOWS_TO` patterns.
 
 ## Common Schema
 
@@ -94,6 +101,8 @@ cia mcp call graph_query \
   'query=USE facts MATCH (a:Address {address: "FULL_ADDRESS"})-[:HAS_LABEL]->(label:AddressLabel) RETURN label.label AS label, label.entity_type AS entity_type, label.address_type AS address_type, label.source AS source LIMIT 25'
 ```
 
+More examples: `references/memgraph-examples.md`.
+
 ## Hard Stops
 
 - No writes or catalog changes: no `CREATE`, `MERGE`, `SET`, `DELETE`,

package/skills/chain-insights-cypher/references/memgraph-examples.md

@@ -0,0 +1,193 @@
+# GraphRAG MCP Cypher Examples
+
+Use these examples when an investigation needs practical graph-language reads
+instead of only schema probes. They are adapted from Memgraph query and deep
+path traversal features, then bounded to the Chain Insights GraphRAG MCP
+surface.
+
+Official Memgraph references:
+
+- Querying: https://memgraph.com/docs/querying
+- Deep path traversal: https://memgraph.com/docs/advanced-algorithms/deep-path-traversal
+
+## Staging Validation
+
+Validated against hosted staging on 2026-05-29 with `network=bittensor` and
+`per_query_timeout_seconds=5`.
+
+Accepted through GraphRAG MCP:
+
+- `MATCH`, directed relationship patterns, property equality, `WHERE`
+- `STARTS WITH`
+- `WITH`, `count`, `sum`
+- `CASE`
+- `ORDER BY`, explicit `LIMIT`
+- fixed-hop patterns written as explicit relationships
+- simple `archive_topology` counts and filtered projections
+- `facts` `Address` projection
+
+Rejected through the current hosted path with a generic backend error:
+
+- variable-length relationship syntax such as `[:FLOWS_TO*1..2]`
+- Memgraph native BFS syntax such as `*BFS` and `USING HOPS LIMIT`
+- weighted/all/K shortest path operators: `*WSHORTEST`, `*ALLSHORTEST`,
+  `*KSHORTEST`
+- `OPTIONAL MATCH`
+- `UNION ALL`
+
+Treat rejected syntax as direct-Memgraph reference material only unless the
+current endpoint accepts the exact query. For Chain Insights agents, use the
+fixed-hop `graph_query_batch` fallback below for traversal.
+
+## Live Topology Examples
+
+Top outflows by amount:
+
+```bash
+cia mcp call graph_query \
+  network=bittensor \
+  'query=USE live_topology MATCH (src:Address)-[flow:FLOWS_TO]->(dst:Address) RETURN src.address AS from_address, dst.address AS to_address, flow.amount_sum AS amount_sum, flow.amount_usd_sum AS amount_usd_sum, flow.tx_count AS tx_count, flow.last_seen_timestamp AS last_seen_timestamp ORDER BY flow.amount_sum DESC LIMIT 25'
+```
+
+Rank addresses by live out-degree and transferred amount:
+
+```bash
+cia mcp call graph_query \
+  network=bittensor \
+  'query=USE live_topology MATCH (src:Address)-[flow:FLOWS_TO]->(dst:Address) WITH src, count(dst) AS out_degree, sum(flow.amount_sum) AS total_amount RETURN src.address AS address, out_degree, total_amount ORDER BY out_degree DESC LIMIT 25'
+```
+
+Bucket flows for quick triage:
+
+```bash
+cia mcp call graph_query \
+  network=bittensor \
+  'query=USE live_topology MATCH (src:Address)-[flow:FLOWS_TO]->(dst:Address) RETURN src.address AS from_address, dst.address AS to_address, CASE WHEN flow.amount_sum IS NULL THEN "unknown" WHEN flow.amount_sum >= 100 THEN "large" WHEN flow.amount_sum >= 10 THEN "medium" ELSE "small" END AS amount_bucket, flow.amount_sum AS amount_sum LIMIT 25'
+```
+
+Prefix search for address completion:
+
+```bash
+cia mcp call graph_query \
+  network=bittensor \
+  'query=USE live_topology MATCH (a:Address) WHERE a.address STARTS WITH "5Ggf" RETURN a.address AS address, a.address_type AS address_type, a.network AS network LIMIT 10'
+```
+
+Address-family census for a combined network:
+
+```bash
+cia mcp call graph_query \
+  network=bittensor \
+  'query=USE live_topology MATCH (a:Address) RETURN a.address_type AS address_type, a.network AS source_network, count(a) AS addresses ORDER BY addresses DESC LIMIT 10'
+```
+
+Bittensor EVM-pallet flow under the same investigation network:
+
+```bash
+cia mcp call graph_query \
+  network=bittensor \
+  'query=USE live_topology MATCH (src:Address {address: "0x20d09f2881602eee806147ceee9275d33ff31df8"})-[flow:FLOWS_TO]->(dst:Address) RETURN src.address AS from_address, src.address_type AS from_type, src.network AS from_network, dst.address AS to_address, dst.address_type AS to_type, dst.network AS to_network, flow.amount_sum AS amount_sum LIMIT 10'
+```
+
+## Archive Topology Examples
+
+Recent historical flows:
+
+```bash
+cia mcp call graph_query \
+  network=bittensor \
+  'query=USE archive_topology MATCH (src:Address)-[flow:FLOWS_TO]->(dst:Address) RETURN src.address AS from_address, dst.address AS to_address, flow.period_granularity AS period_granularity, flow.amount_sum AS amount_sum, flow.tx_count AS tx_count, flow.last_seen_timestamp AS last_seen_timestamp ORDER BY flow.last_seen_timestamp DESC LIMIT 25'
+```
+
+Count archive flow edges by granularity:
+
+```bash
+cia mcp call graph_query \
+  network=bittensor \
+  'query=USE archive_topology MATCH (:Address)-[flow:FLOWS_TO]->(:Address) RETURN flow.period_granularity AS period_granularity, count(flow) AS flow_edges LIMIT 10'
+```
+
+Filter daily archive flows:
+
+```bash
+cia mcp call graph_query \
+  network=bittensor \
+  'query=USE archive_topology MATCH (src:Address)-[flow:FLOWS_TO]->(dst:Address) WHERE flow.period_granularity = "daily" RETURN src.address AS from_address, dst.address AS to_address, flow.amount_sum AS amount_sum, flow.tx_count AS tx_count ORDER BY flow.amount_sum DESC LIMIT 25'
+```
+
+Remember that archive numeric fields may arrive as strings.
+
+## Facts Examples
+
+Facts `Address` projection:
+
+```bash
+cia mcp call graph_query \
+  network=bittensor \
+  'query=USE facts MATCH (a:Address) RETURN a.address AS address, a.labels AS labels, a.is_exchange AS is_exchange LIMIT 25'
+```
+
+Only use richer fact labels or relationships after a fresh schema probe proves
+the current network exposes them. On 2026-05-29, staging accepted facts
+`Address` projection but rejected `Address` to `AddressLabel` relationship
+samples.
+
+## Fixed-Hop Traversal Fallback
+
+Memgraph deep traversal docs cover BFS, weighted shortest path, all shortest
+paths, and K shortest paths. Through the current GraphRAG MCP path, those
+native operators were rejected on staging. Use explicit fixed-hop batches for
+Chain Insights traversal instead.
+
+One-hop path:
+
+```bash
+cia mcp call graph_query_batch \
+  network=bittensor \
+  per_query_timeout_seconds=5 \
+  'queries=[{"id":"hop_1","query":"USE live_topology MATCH (src:Address {address: \"FULL_SOURCE_ADDRESS\"})-[r1:FLOWS_TO]->(dst:Address {address: \"FULL_TARGET_ADDRESS\"}) RETURN src.address AS from_address, dst.address AS to_address, 1 AS hops, r1.amount_sum AS amount_sum, r1.tx_count AS tx_count LIMIT 25"}]'
+```
+
+Two-hop expansion with exchange-stopped intermediate nodes:
+
+```bash
+cia mcp call graph_query_batch \
+  network=bittensor \
+  per_query_timeout_seconds=5 \
+  'queries=[{"id":"hop_2","query":"USE live_topology MATCH (src:Address {address: \"FULL_SOURCE_ADDRESS\"})-[r1:FLOWS_TO]->(mid:Address)-[r2:FLOWS_TO]->(dst:Address) WHERE mid.is_exchange IS NULL RETURN src.address AS from_address, mid.address AS mid_address, dst.address AS to_address, 2 AS hops, r1.amount_sum AS first_amount, r2.amount_sum AS second_amount LIMIT 25"}]'
+```
+
+Generate one query per depth when investigating a path. Keep each query
+directed, stop expansion at exchange nodes, preserve full addresses, and use a
+small `LIMIT` while exploring.
+
+## Direct Memgraph Reference Syntax
+
+Use this syntax only in a direct Memgraph console or after the GraphRAG MCP
+endpoint accepts the same pattern.
+
+Native BFS:
+
+```cypher
+MATCH path=(src:Address {address: "FULL_SOURCE_ADDRESS"})-[:FLOWS_TO *BFS]->(dst:Address {address: "FULL_TARGET_ADDRESS"})
+RETURN path
+LIMIT 5;
+```
+
+Weighted shortest path:
+
+```cypher
+MATCH path=(src:Address {address: "FULL_SOURCE_ADDRESS"})-[:FLOWS_TO *WSHORTEST (r, n | coalesce(r.amount_sum, 1)) total_weight]->(dst:Address {address: "FULL_TARGET_ADDRESS"})
+RETURN path, total_weight
+LIMIT 5;
+```
+
+K shortest alternatives:
+
+```cypher
+MATCH (src:Address {address: "FULL_SOURCE_ADDRESS"}), (dst:Address {address: "FULL_TARGET_ADDRESS"})
+WITH src, dst
+MATCH path=(src)-[:FLOWS_TO *KSHORTEST|3]->(dst)
+RETURN path
+LIMIT 3;
+```